Errors
Status codes, error codes and what to do.
Errors are JSON with a stable code, a human message and the request_id. No error is charged.
{ "error": { "code": "no_credits", "message": "balance is zero; buy a credit pack" }, "request_id": "..." }| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | bad_request | a parameter is missing or malformed | fix the request |
| 401 | missing_key, invalid_key | no key, or a revoked key | check the header |
| 402 | no_credits | balance is zero | buy a pack |
| 403 | access_denied | X does not serve this object to the reading session | try later, or a different object |
| 403 | product_unavailable | search product not available, for example Top | use Latest |
| 404 | not_found | no such user or tweet, or it is protected | nothing |
| 429 | rate_limited | over your requests-per-second limit | wait retry-after seconds |
| 503 | upstream_rate_limited, no_account, busy | X or our pool is saturated right now | retry after retry-after seconds, with backoff |
| 502 | upstream_error, query_id_stale, request_rejected | X changed something on its side | retry once; if it persists we are already paged |
| 500 | internal | our bug | send us the request_id |
Retry policy we recommend
Retry 503 and 502 up to three times with 2, 4 and 8 seconds between attempts. Do not retry 4xx.
Because failed requests are free, retries never cost credits.