> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twexapi.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate Limits

> TwexAPI throughput limits, 429 handling, Retry-After behavior, and pagination-safe backoff for production jobs.

TwexAPI applies rate limits to protect account stability and upstream X/Twitter fetch capacity. Design exports, agent loops, and scheduled jobs to respect limits instead of retrying at full speed after every failure.

## Throughput expectations

TwexAPI is built for production workloads. Marketing benchmarks cite up to **100 requests per second per client** under normal conditions, but your effective limit depends on endpoint type, account tier, and current platform load.

Treat published throughput as an upper bound—not a target for every integration.

| Workload           | Guidance                                                                    |
| ------------------ | --------------------------------------------------------------------------- |
| Interactive agents | Call `explore` once per task, then batch related `twexapi_request` calls.   |
| Follower exports   | Paginate with cursors; add delay between pages on large accounts.           |
| Scheduled jobs     | Stagger start times; avoid launching every workflow at `:00`.               |
| Write actions      | Keep write volume lower than read volume; require human approval in agents. |

## When you hit a limit

Exceeded limits return HTTP **`429 Too Many Requests`**. Some responses include a **`Retry-After`** header (seconds until retry is reasonable). When present, wait at least that many seconds before the next call.

Typical response shape:

```json theme={null}
{
  "detail": "Rate limit exceeded. Try again later."
}
```

On MCP, `twexapi_request` surfaces the same status inside the tool result. Preserve cursors and completed rows before backing off.

## Recovery checklist

<Steps>
  <Step title="Stop burst traffic">
    Pause loops, Prefect flows, n8n batches, or agent tool chains that fired many requests in a short window.
  </Step>

  <Step title="Read Retry-After when present">
    Sleep for the header value. If absent, start with 5–15 seconds and increase on repeated `429`s.
  </Step>

  <Step title="Resume from the last cursor">
    Retry the **same page**, not the next one, so you do not skip or duplicate rows.
  </Step>

  <Step title="Lower steady-state QPS">
    Add inter-request delay or reduce worker concurrency before restarting the job.
  </Step>
</Steps>

## Backoff example

Python with optional `Retry-After`:

```python theme={null}
import time
import requests

def call_with_backoff(fn, max_attempts=5):
    delays = [5, 15, 45, 120, 300]
    for attempt in range(max_attempts):
        response = fn()
        if response.status_code != 429:
            return response

        retry_after = response.headers.get("Retry-After")
        wait = int(retry_after) if retry_after and retry_after.isdigit() else delays[min(attempt, len(delays) - 1)]
        time.sleep(wait)

    return response
```

Prefect users can mirror the same delays with `retry_delay_seconds`—see [Prefect guide](/guides/prefect).

## Design patterns that avoid 429

### Paginate instead of parallelizing identical reads

Fetching page 1 twenty times in parallel does not speed up a single export. Walk cursors sequentially unless endpoints explicitly support independent shards.

### Separate read and write schedules

Writes often have stricter practical limits than reads. Run posting, likes, and follows on a slower queue than search and profile lookups.

### Cache stable lookups

Store `user_id`, profile fields, and tweet metadata when downstream steps reuse them. Fewer duplicate lookups means fewer counted requests.

### Use MCP `explore` sparingly

Discovery calls still count toward usage. Cache the chosen `method` and `path` for the duration of a job.

## No-code and agent platforms

| Platform                       | Pattern                                                           |
| ------------------------------ | ----------------------------------------------------------------- |
| [n8n](/guides/n8n)             | Add Wait nodes after `429`; store cursor in workflow static data. |
| [Zapier](/guides/zapier)       | Use built-in replay with delay; alert ops on repeated failures.   |
| [Make](/guides/make)           | Route `429` to a sleep module before retrying the HTTP module.    |
| [Pipedream](/guides/pipedream) | Split large exports; cap concurrent steps per workflow.           |

Platform **webhooks** (Catch Hook, Custom Webhook) receive agent handoffs—they are not TwexAPI-native event streams. Schedule REST follow-up calls with backoff after webhook ingestion.

## MCP vs REST

Both paths share the same account limits and credit model. An agent that loops `twexapi_request` without delay can trigger `429` as quickly as a tight SDK loop.

For long-running production exports, prefer direct REST or an SDK with explicit retry policy over an autonomous agent loop.

## Monitoring rate-limit health

Log these fields per request:

* HTTP status
* Endpoint path
* Cursor or page index
* Retry attempt number
* `Retry-After` when present

Alert when `429` rate exceeds a threshold for a single API key or workflow.

## Related pages

* [Error Handling](/guides/error-handling)
* [Authentication](/authentication)
* [API Overview](/api-reference/overview)
* [Agent MCP Handoff](/mcp/agent-handoff)