Rate Limits - twexapi

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:

{
  "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

Stop burst traffic

Pause loops, Prefect flows, n8n batches, or agent tool chains that fired many requests in a short window.

Read Retry-After when present

Sleep for the header value. If absent, start with 5–15 seconds and increase on repeated 429s.

Resume from the last cursor

Retry the same page, not the next one, so you do not skip or duplicate rows.

Lower steady-state QPS

Add inter-request delay or reduce worker concurrency before restarting the job.

Backoff example

Python with optional Retry-After:

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.

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	Add Wait nodes after `429`; store cursor in workflow static data.
Zapier	Use built-in replay with delay; alert ops on repeated failures.
Make	Route `429` to a sleep module before retrying the HTTP module.
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.

​Throughput expectations

​When you hit a limit

​Recovery checklist

​Backoff example

​Design patterns that avoid 429

​Paginate instead of parallelizing identical reads

​Separate read and write schedules

​Cache stable lookups

​Use MCP explore sparingly

​No-code and agent platforms

​MCP vs REST

​Monitoring rate-limit health

​Related pages