Error Handling

Error response format

All API errors return a JSON body with an error field:

{
  "error": "Human-readable error message"
}

HTTP status codes

Code	Meaning	What to do
`400`	Bad Request	Check your request body and parameters.
`401`	Unauthorized	Verify your API key is valid and included in the Authorization header.
`403`	Forbidden	Your API key doesn't have the required scope or role.
`404`	Not Found	The requested resource doesn't exist.
`409`	Conflict	A resource with the same identifier already exists.
`429`	Too Many Requests	You've hit the rate limit. Wait and retry after the `Retry-After` header.
`500`	Internal Server Error	Something went wrong on our end. Retry with exponential backoff.

Rate limit headers

Every response includes rate limit information:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1706000000
Retry-After: 3600

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed in the current window.
`X-RateLimit-Remaining`	Requests remaining in the current window.
`X-RateLimit-Reset`	Unix timestamp when the rate limit window resets.
`Retry-After`	Seconds to wait before retrying (only on 429 responses).

Retry strategy

For 429 and 5xx errors, implement exponential backoff:

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const response = await fetch(url, options);
 
    if (response.ok) return response;
 
    if (response.status === 429 || response.status >= 500) {
      if (attempt === maxRetries) throw new Error(`Failed after ${maxRetries} retries`);
 
      const retryAfter = response.headers.get('Retry-After');
      const delay = retryAfter
        ? parseInt(retryAfter) * 1000
        : Math.min(1000 * Math.pow(2, attempt), 30000);
 
      await new Promise(resolve => setTimeout(resolve, delay));
      continue;
    }
 
    // Non-retryable error
    const body = await response.json();
    throw new Error(body.error || `HTTP ${response.status}`);
  }
}

Error response format

HTTP status codes

Rate limit headers

Retry strategy

On this page