When the API says no

The shape of an error response, and what it means.

Error responses always have the same shape, so you can handle them in one place.

{ "success": false, "error": { "code": "UNAUTHENTICATED", "message": "..." } }

The ones you will see

Status	Meaning	What to do
401	Key wrong, revoked, or not sent	Check the Authorization header.
403	The key is valid but not permitted	Likely an ordinary key calling a reseller endpoint.
422	The payload failed validation	Read the message — it names the field.
429	Rate limited	Wait as instructed, then retry.
503	Our proxy network could not be reached for now	Wait as Retry-After says if it is sent (if not, wait a few seconds and back off further each time), then send the same request again. This is not a fault in your request.

Retrying

Retry on 429 and 503, backing off as you go. A 502 or 504 is never our answer — it is a page from the CDN in front of our servers; treat it like a 503. Do not retry 401, 403 or 422 — the same request will be refused the same way.