Errors

Errors come back as JSON with an HTTP status that matches the problem:

{ "error": "invalid_api_key", "message": "The key is invalid, expired or revoked." }

Branch on error, which never changes for a given problem. message is for people and its wording may change.

Error Codes

Status	error	What to do
401	missing_api_key	Send the key as Authorization: Bearer <key>.
401	invalid_api_key	Check the key, or create a new one if it expired or was revoked.
403	ip_not_allowed	The key has an IP allowlist that does not include this address. Call from an allowed address, or use another key.
403	insufficient_scope	The key is read-only and the request is not a GET or HEAD. Use a key with full access.
404	not_found	The path does not exist. Check it against the API Reference.
429	rate_limited	Wait for the Retry-After seconds, then retry. See Rate Limits.
500	internal_error	Something failed on our side. Retry with backoff; if it keeps happening, contact support.

Retrying Safely

Retry only 429 and 500 responses, and only after a delay that grows with each attempt. A 401, 403 or 404 will fail the same way every time until the request changes.