Errors

Errors use HTTP status codes and one JSON shape:

{
  "error": {
    "code": "invalid_parameters",
    "message": "The request parameters are invalid.",
    "request_id": "..."
  }
}

message is written for people and safe to show to your users. Branch on code, not on message. No error is ever billed: X-Credits-Used is 0.

Status	Code	Meaning
401	`invalid_api_key`	Missing, unknown or revoked API key.
402	`insufficient_credits`	Your credit balance is used up. Buy more credits to continue.
403	`restricted_endpoint`	This endpoint requires accepting the restricted-endpoint terms in your dashboard.
404	`unknown_endpoint`	No such endpoint. See the API reference for available endpoints.
404	`not_found`	No data was found for these parameters. You were not charged.
410	`endpoint_retired`	This endpoint has been retired.
422	`invalid_parameters`	The request parameters are invalid.
429	`rate_limited`	Too many requests. Retry after the number of seconds in the Retry-After header.
502	`source_error`	The data source returned an error. You were not charged.
503	`temporarily_unavailable`	The data source is busy. Retry after the number of seconds in the Retry-After header. You were not charged.
504	`timeout`	The data source did not answer within 60 seconds. You were not charged.

Retrying

Retry after a wait: 429 rate_limited and 503 temporarily_unavailable carry a Retry-After header in seconds.
Retry later, perhaps with other parameters: 502 source_error and 504 timeout.
Don’t retry unchanged: 401, 402, 403, 404, 410 and 422 will fail the same way until you change the key, the balance, the terms or the request.

Quote the request_id when you contact support.