Skip to main content

Error Handling

Error Response Format

All errors follow a consistent JSON structure:

Error Types

Automatic Retries

The SDK automatically retries failed requests for transient errors (429, 5xx) with exponential backoff:

Retry Behavior

  • Initial delay: 0.5 seconds
  • Backoff factor: 2x (0.5s → 1s → 2s → 4s)
  • Jitter: ±25% randomization to prevent thundering herd
  • Retry-After: Server header takes precedence when present
  • Max delay: 30 seconds cap

Exception Hierarchy

Handling Errors

Request IDs

Every response includes a unique X-Request-Id header. Include this when contacting support:

Rate Limit Headers

Successful responses include rate limit information: