Errors
Every API answers errors in one format, with a stable code, and failed calls are never billed.
Error format
Any response with a status of 400 or more has this body, whatever the API or the endpoint:
{
"error": {
"code": "invalid_parameter",
"message": "Some parameters are not valid.",
"request_id": "req_8f2c1a9b0d3e4f5a6b7c",
"details": [{ "param": "limit", "message": "must be <= 100" }]
}
}code: a stable, machine-readable string in snake_case. Branch on it in your code.message: a human-readable explanation. It can change wording at any time, so show it or log it, but do not parse it.request_id: the id of the call, also sent in theX-Request-Idheader. Quote it when you contact support. It isreq_nonewhen the request was rejected before reaching an endpoint (an unknown path, a method other than GET, a malformed request).details: present only on some errors. Forinvalid_parameterit is a list with one{"param", "message"}entry per problem; forinsufficient_creditsit is{"required", "available"}; some APIs add details to their own 4xx errors.
An example of a balance that is too low for the call:
{
"error": {
"code": "insufficient_credits",
"message": "This call needs at least 3 credits and your balance is 0. Top up at https://scrapecrate.com/dashboard/billing.",
"request_id": "req_3b9d0c7e1f2a4b6c8d0e",
"details": { "required": 3, "available": 0 }
}
}Status codes and error codes
| Status | Code | Meaning | Retry? |
|---|---|---|---|
| 400 | invalid_parameter | A parameter is missing, unknown or invalid. details lists each problem as {"param", "message"}, e.g. "is required", "must be <= 100", "unknown parameter". | No: fix the request |
| 400 | invalid_cursor | The cursor is not valid for this endpoint. | No |
| 401 | missing_api_key | No API key in the X-API-Key header or the Authorization: Bearer header. | No |
| 401 | invalid_api_key | The key is wrong, disabled or deleted. | No |
| 402 | insufficient_credits | Your balance is below the minimum price of the call. details is {"required", "available"}. | After a top-up |
| 403 | account_disabled | The account is suspended. | No: contact support |
| 404 | not_found, *_not_found | The video, place, company, ad... does not exist or is not public (an API can use a more specific code ending in _not_found). Also an unknown endpoint path. | No |
| 405 | method_not_allowed | Every endpoint is GET. | No |
| 410 | cursor_expired | The cursor is too old: start again from the first page. | Restart the list |
| 429 | rate_limited | Over 300 requests per minute for the key (or over the per-IP limit). | Yes, after Retry-After |
| 429 | too_many_concurrent_requests | More than 20 requests in flight for the key. | Yes, after Retry-After |
| 429 | insufficient_credits_retry_later | The key kept retrying with no credits left, so its requests are paused for a while. details is {"retry_after"}; a top-up lifts the pause within seconds. | After a top-up, or after Retry-After |
| 500 | internal_error | Unexpected error on our side. | Yes, with backoff |
| 501 | not_available | This endpoint is not available yet. | No |
| 502 | source_error | The data source returned an unexpected answer. | Yes, with backoff |
| 503 | not_available | This API is not available yet (announced, not launched). Nothing is charged. | No: it will not work until launch |
| 503 | source_unavailable | The data source is temporarily unavailable. | Yes, with backoff (Retry-After when present) |
| 503 | source_busy | The data source is saturated. | Yes, after Retry-After |
| 504 | source_timeout | The data source took too long to answer. | Yes |
Two codes can share a status: 503 not_available means the API has been announced but is not launched yet, and retrying does not help; 503 source_unavailable is a temporary problem that goes away by itself. That is why your code should look at error.code and not only at the HTTP status.
Errors are free
Only successful (200) calls cost credits. When a call fails, the credits reserved for it are released at once: error responses that reach the balance check carry X-Credits-Used: 0 and your unchanged X-Credits-Remaining. Not-found results, timeouts and unavailable data sources are never billed, so a retry costs nothing either.
Retrying
Retry 429 and the temporary 5xx errors (internal_error, source_error, source_unavailable, source_busy, source_timeout) with exponential backoff, for example 1 s, 2 s, 4 s, up to 5 attempts, and honour Retry-After when the response has it. Do not retry 4xx errors other than 429: the same request will fail the same way. Cursors that expire (410 cursor_expired) mean starting the list again from the first page.
The Python and TypeScript SDKs retry 429, 500, 502, 503 and 504 up to 3 times by default, then raise a typed error: ValidationError (400), AuthenticationError (401), InsufficientCreditsError (402), PermissionDeniedError (403), NotFoundError (404), RateLimitError (429) and ServiceUnavailableError (5xx), all subclasses of ApiError with status, code, message, the request id and details. See code examples for error handling in practice.