Handle API failures
Check the HTTP status before reading a successful response. V2 uses an error object with a stable code and a human-readable message for expected request errors.
| Status | V2 code | What to check |
|---|---|---|
| 401 | unauthorized | Missing, invalid or archived API key |
| 403 | forbidden | Organization access |
| 404 | not_found | Identifier, route and key's organization |
| 405 | method_not_allowed | HTTP method |
| 422 | invalid_request | Positive identifiers, page and page size |
A missing record and a record belonging to another organization both return 404. Do not infer whether another organization owns an identifier. A 5xx response can originate in the gateway or backend; it may not contain the API error object. Retry reads with a bounded delay and record the time and route for diagnosis.
V1 retains its existing detail response, including validation details. Match error handling to the version of the endpoint you called. Do not automatically retry a v1 call-initiation request after a timeout: first check whether the call was created.