Errors and how to handle them

Error shape

Every error comes back as JSON in the same shape:

{
  "error": {
    "code": "invalid_input",
    "message": "Input should be greater than or equal to 1850",
    "field": "year"
  }
}

code: a short code for your program to check. Codes do not change.
message: what went wrong, in plain English. The wording can change, so show it or log it, but do not match on it.
field: the request field that caused the error, when one field did.

Every response also has an X-Request-Id header. Include it when you contact support about a request.

Status	Code	What it means and what to do
400	invalid_json	The request body is not valid JSON. Check the body you send.
401	unauthorized	The API key is missing, wrong or revoked. Send a valid key. See authentication.
403	account_suspended	The account that owns the key is suspended, so none of its keys work. Do not retry. Contact us.
404	not_found	The path does not exist, or a name in it is unknown (for example a festival). The message lists the names you can use.
405	method_not_allowed	Wrong HTTP method for this path. The Allow header lists the right one.
413	payload_too_large	The request body is larger than 64 KB.
422	invalid_input	A field is missing or out of range, such as a year before 1850. The field property names it. A local time that happens twice (when clocks go back) is also refused: send timezone_fold as 0 or 1.
429	rate_limited, quota_exceeded, test_quota_exceeded	This key made too many calls this minute, your live keys used up the monthly quota, or your test keys used up the monthly test allowance. Wait for Retry-After seconds, or move to a bigger plan in Billing.
502, 503, 504	bad_gateway, unavailable, timeout	A temporary problem on our side. Retry after a short wait.

429: wait the number of seconds in Retry-After, then retry.
502, 503 and 504: retry after a short wait, and wait longer after each failure (for example 1, 2, then 4 seconds).
Any other 4xx: do not retry. Fix the request first; the same request will fail the same way.

Every endpoint lists its responses in the API reference.