Core concepts
Understand error codes and messages, and decide which failed requests are safe to retry.
The error format
Every error response has the same shape, so you can handle all failures with one code path:
{
"error": {
"code": "invalid_parameter",
"message": "The 'limit' parameter must be between 1 and 100.",
"request_id": "req_8k3j2l"
}
}
The code is stable and safe to branch on. The message is for humans and can change. Include the request_id whenever you contact support.
Common status codes
| Status | Meaning | Retry? |
|---|---|---|
400 Bad Request | Malformed request. | No. Fix the request. |
401 Unauthorized | Missing, revoked, or mistyped credential. | No. Fix the credential. |
403 Forbidden | Your application isn't registered with this API. | No. Register first. |
404 Not Found | The resource doesn't exist. | No. |
422 Unprocessable Entity | The request is valid JSON but fails validation. | No. Fix the data. |
429 Too Many Requests | Rate limit exceeded. | Yes, after Retry-After. |
500 Internal Server Error | Something failed on our side. | Rarely. Retry with backoff. |
503 Service Unavailable | Temporary outage or maintenance. | Yes, with backoff. |
The short version: 4xx means something in your request needs to change. 5xx means the failure was ours, and a retry may help.
Retry with backoff
For the retryable statuses, use exponential backoff with jitter:
async function requestWithRetry(url, options, maxRetries = 3) {
for (let attempt = 0; attempt <= maxRetries; attempt++) {
const response = await fetch(url, options)
if (response.ok) return response
const retryable = response.status === 429 || response.status >= 500
if (!retryable || attempt === maxRetries) throw new Error(`Request failed: ${response.status}`)
const retryAfter = Number(response.headers.get('Retry-After'))
const delay = Math.max(Number.isFinite(retryAfter) ? retryAfter * 1000 : 0, 1000 * 2 ** attempt)
await new Promise(resolve => setTimeout(resolve, delay))
}
}
Only retry safe operations
A GET request is always safe to retry. Before retrying a POST that creates something, use an idempotency key. See Idempotent requests.