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

StatusMeaningRetry?
400 Bad RequestMalformed request.No. Fix the request.
401 UnauthorizedMissing, revoked, or mistyped credential.No. Fix the credential.
403 ForbiddenYour application isn't registered with this API.No. Register first.
404 Not FoundThe resource doesn't exist.No.
422 Unprocessable EntityThe request is valid JSON but fails validation.No. Fix the data.
429 Too Many RequestsRate limit exceeded.Yes, after Retry-After.
500 Internal Server ErrorSomething failed on our side.Rarely. Retry with backoff.
503 Service UnavailableTemporary 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.

Next steps