Error format
402 Payment Required
{
"detail": "credit too low; add credit to continue",
"error": {
"code": "credit_too_low",
"message": "credit too low; add credit to continue",
"requestId": "8f2c…"
}
}Branch on error.code, not the message. Every response has an x-request-id header; include it when contacting support. You can send your own X-Request-ID (letters, digits, ., _, -, up to 80 characters).
Common codes
| Status | Code | Meaning | What to do |
|---|---|---|---|
400 | validation_error | A parameter has the wrong format. | Fix the request. |
400 | limit_removed | limit was sent to a live route. | Remove it and paginate with cursor. |
401 | unauthorized | Missing or invalid API key. | Check the Authorization header. |
402 | credit_too_low | Balance cannot cover one page. | Add credit. |
402 | queued_balance_too_low | Jobs need $1 of available balance. | Add credit. |
404 | user_not_found, tweet_not_found, community_not_found, job_not_found | The requested item does not exist or is not public. | Do not retry. |
429 | overloaded, capacity_limited, rate_limited | The service or upstream capacity is busy. | Retry after Retry-After seconds, or with backoff. |
502 | upstream_transport, malformed_upstream | X returned an unusable response. | Retry with backoff. |
503 | account_unavailable, retry_exhausted | No upstream session could complete the request. | Retry later. |
504 | upstream_timeout | X did not answer in time. | Retry with backoff. |
Retries
Retry 429 and 5xx with exponential backoff and a cap on attempts. Fix the request before retrying 400, 401, 402 or 404. A successful retry is charged once.
How credit is charged
- A request needs at least
$0.001of balance, and enough to cover the largest possible page for that route. - That maximum is reserved when the request starts. When the page arrives you pay for the records it contains and the rest is returned.
- A request that fails is refunded in full.
- Single lookups (profile, account information, post, community) cost $0.001 each.
- Collections are priced per record; see pricing. The response level does not change the price.