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 the X-Request-Id header. Quote it when you contact support. It is req_none when 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. For invalid_parameter it is a list with one {"param", "message"} entry per problem; for insufficient_credits it 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

StatusCodeMeaningRetry?
400invalid_parameterA 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
400invalid_cursorThe cursor is not valid for this endpoint.No
401missing_api_keyNo API key in the X-API-Key header or the Authorization: Bearer header.No
401invalid_api_keyThe key is wrong, disabled or deleted.No
402insufficient_creditsYour balance is below the minimum price of the call. details is {"required", "available"}.After a top-up
403account_disabledThe account is suspended.No: contact support
404not_found, *_not_foundThe 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
405method_not_allowedEvery endpoint is GET.No
410cursor_expiredThe cursor is too old: start again from the first page.Restart the list
429rate_limitedOver 300 requests per minute for the key (or over the per-IP limit).Yes, after Retry-After
429too_many_concurrent_requestsMore than 20 requests in flight for the key.Yes, after Retry-After
429insufficient_credits_retry_laterThe 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
500internal_errorUnexpected error on our side.Yes, with backoff
501not_availableThis endpoint is not available yet.No
502source_errorThe data source returned an unexpected answer.Yes, with backoff
503not_availableThis API is not available yet (announced, not launched). Nothing is charged.No: it will not work until launch
503source_unavailableThe data source is temporarily unavailable.Yes, with backoff (Retry-After when present)
503source_busyThe data source is saturated.Yes, after Retry-After
504source_timeoutThe 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.