Rate limits

The limits the Social Fetch API enforces: no requests-per-second cap on paid lookups with an API key, 200 requests in flight per workspace, per-minute limits on free routes and keyless calls, and how 429, 503 and Retry-After work.

Paid lookups sent with an API key have no request quota and no requests-per-second limit. Your credit balance is what limits them, plus a cap of 200 requests in flight per workspace. Free routes and requests sent without a key have per-minute limits.

Every limit is the same on every plan.

Limits by route

RequestsLimitCounted perWhen you go over
Paid lookups (/v1/**, /v2/**) with an x-api-keyNo per-minute limit. 200 requests in flight at once.Workspace (all its keys together)503 temporarily_unavailable, reason: "concurrency_limit", Retry-After: 1
Requests without an API key (x402 payments, or a missing key)60 per minuteClient IP address429 temporarily_unavailable with Retry-After
GET /v1/whoami30 per minuteUser429 temporarily_unavailable with Retry-After
GET /v1/balance30 per minuteWorkspace429 temporarily_unavailable with Retry-After
GET /health60 per minuteClient IP address429 temporarily_unavailable with Retry-After
POST /v1/query/validate60 per minuteWorkspace429 temporarily_unavailable with Retry-After
POST /v1/query/suggest10 per minute and 300 per dayWorkspace429 temporarily_unavailable with Retry-After
Webhook endpoint test sends10 per minuteWebhook endpoint429 with Retry-After
Webhook redeliveries30 per minuteWebhook endpoint429 with Retry-After
MCP (/mcp), signed in600 per minuteSigned-in user503 temporarily_unavailable with Retry-After
MCP, not signed in60 per minute, and 15 unpaid tool calls per minuteClient IP address429 temporarily_unavailable with Retry-After

Per-minute limits use a sliding one-minute window, not a fixed clock minute.

The in-flight cap isn't a rate: a slot frees as soon as a request finishes, so a workspace can send far more than 200 requests a minute as long as no more than 200 are running at once.

Headers

  • Retry-After: sent with every 429 and with 503 temporarily_unavailable. It's a whole number of seconds to wait before retrying.
  • X-Request-Id: sent on every response. Quote it to support.

The API doesn't send X-RateLimit-Limit, X-RateLimit-Remaining or RateLimit-* headers. Use Retry-After when you're refused, and GET /v1/balance (free) to see how many credits are left.

What a refusal looks like

A 429 has the same { error } body as every other error:

HTTP/1.1 429 Too Many Requests
Retry-After: 12
Content-Type: application/json

{
  "error": {
    "code": "temporarily_unavailable",
    "message": "This endpoint is temporarily rate limited. Retry later.",
    "requestId": "req_..."
  }
}

Going over the in-flight cap returns 503 with reason:

{
  "error": {
    "code": "temporarily_unavailable",
    "message": "Too many requests in progress for this account (limit 200 at once). Retry after a request finishes.",
    "requestId": "req_...",
    "reason": "concurrency_limit"
  }
}

Neither response costs credits.

Retrying

  1. On 429 or 503, wait the number of seconds in Retry-After, then retry the same request.
  2. If there's no Retry-After, back off with a growing, jittered delay (for example 1 s, 2 s, 4 s).
  3. To stay under the in-flight cap, run paid lookups through a worker pool of at most 200 per workspace.
  4. Don't retry 402 insufficient_credits in a loop: add credits first. See Credits.

To check that you're within a limit from the terminal:

curl -sS -i \
  -H "x-api-key: $SOCIALFETCH_API_KEY" \
  "https://api.socialfetch.dev/v1/balance"

A full retry wrapper is in Errors.

On this page