Core Concepts8 min read
Handling Errors and Retries
HTTP codes, error format, and retry strategies.
Error response format
Errors follow the same envelope as success responses, with status: "error" and an error.code / error.message field.
json
{
"status": "error",
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Quota exceeded. Resets at 2026-06-01T00:00:00Z."
},
"timestamp": "2026-05-21T12:00:00Z"
}Common HTTP codes
200 OK · 400 bad params · 401 missing/invalid key · 403 forbidden (plan doesn't include this endpoint) · 404 not found · 429 rate limited · 500 server error · 503 upstream unavailable.
Retry only the safe ones
Retry on 429, 500, 502, 503, 504 with exponential backoff (1s, 2s, 4s, 8s). Never retry on 400, 401, 403 — these will keep failing.
Idempotency keys
POST endpoints that have side effects (email sending, webhook creation) accept an Idempotency-Key header. Retrying with the same key won't duplicate the operation.