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 uniqueX-Request-Id header. Include this when contacting support: