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.

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.

For a message-by-message diagnosis of HTTP 429, X posting code 344, and daily DM limits, use the Twitter API error code reference.

Recovery checklist

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 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
• Authentication
• API Overview
• Agent MCP Handoff