Error Handling
A robust integration handles errors as deliberately as it handles success. The API uses standard HTTP status codes, and every error response includes a human-readable message in the JSON body.
Status codes
- 200 OK. Success. Read the
resultobject. - 400 Bad Request. An input is missing or malformed. Fix the request body; do not retry the same request unchanged.
- 401 or 403. The API key is missing, invalid or not authorized. Check the
X-API-Keyheader. - 429 Too Many Requests. You hit a rate or quota limit. Back off and retry, or buy extra calls or upgrade.
- 5xx. A temporary server error. Retry with a short, increasing backoff.
Good practice
- Read the JSON error message and log it with the request details, so you can debug quickly.
- Distinguish client errors (4xx, which need a fix) from server errors (5xx, which are safe to retry).
- Show your users a friendly message rather than a raw error, and fall back gracefully when a call fails.
Should I retry a 400?
No. A 400 means the request itself is wrong, so retrying it unchanged will fail again. Fix the input first. Retry only 429 and 5xx, with a backoff.