Error response format
All API errors follow the same structure:err_code: machine-readable code for programmatic handlingerrors: field-level detail, present on validation errorsmessage: human-readable summary
HTTP status codes
Retry strategy
For429 and 5xx responses, retry with exponential backoff:
- Wait 1s before the first retry
- Double the wait on each subsequent attempt
- Cap at 30s
- Stop after 3 to 5 attempts and alert your team
4xx responses, retrying the same request will not help. Fix the request first.
What to show users vs what to log
Never expose
err_code or raw error bodies to end users.
Error categories
Authentication failure
A missing header, an expired timestamp, an unknown key or a signature that doesn’t verify. These return HTTP401 with an AUTH_* code. See authentication errors for every code and its fix.