Errors and troubleshooting
Handle structured API failures and use request identifiers to investigate problems.
A consistent error shape
Failures use RFC 9457 application/problem+json. The response includes type, title, status, detail, instance, and errors. instance identifies the request; errors contains field-level issues when applicable.
Respond to the status
| Status | Next step |
|---|---|
400 | Fix malformed JSON or field validation errors. |
401 | Check the bearer token and environment. |
402 | Review balance or spending limits in your console. |
403 | Check account access and key permissions. |
422 | Adjust inputs when no supported route can be found. |
429 | Respect retry guidance and reduce request pressure. |
503 | Use bounded backoff for temporary service unavailability. |
The exact supported errors for an operation appear in its generated reference.
Preserve useful evidence
Log the request identifier, operation, status, and data version when available. Exclude credentials and minimize location data in application logs. When investigating a request, start with its structured detail and field-level errors.
Separate API and network failures
A timeout or interrupted connection can happen before your application receives a response. Avoid assuming the operation was never processed. Inspect usage and bound retries rather than continuously repeating requests.