ReferenceReference
Errors & Troubleshooting
Handle API failures predictably and troubleshoot integrations without exposing sensitive data.
1
HTTP status codes
Use the HTTP status as the primary failure category and the JSON detail field for operator context.
- 400 — request could not be completed with the supplied business data.
- 401 — X-API-Key is missing, invalid, or revoked.
- 404 — the requested resource does not exist.
- 422 — request JSON failed schema validation.
- 429 — the live API-call allowance has been reached.
- 500 — an unexpected server-side failure occurred.
2
Error shape
Most API errors return a JSON detail value.
json
{
"detail": "Missing API Key"
}3
Retry guidance
Do not retry 400, 401, 404, or 422 responses without changing the request. Retry transient 500-series failures with bounded exponential backoff and jitter.
- Set connect and response timeouts.
- Cap automatic retries.
- Make write requests idempotent in your own workflow.
- Surface the final error to an operator.
4
Safe diagnostics
Record the endpoint, status, timestamp, and a redacted response. Never log API keys or complete customer payloads. Use Inbound Logs in the portal to correlate recent activity.