Error Handling
Common Status Codes
Understanding the status codes returned by the API is the first step in handling responses correctly. Here are the most common codes you might encounter:
| Code | Meaning | Description |
|---|---|---|
| 200 | OK | Request successful. The response contains the requested data. |
| 201 | Created | Resource successfully created. Common for POST requests. |
| 400 | Bad Request | Malformed request or missing required parameters. |
| 401 | Unauthorized | Invalid, expired, or missing API key. |
| 402 | Payment Required | Insufficient balance. Top up your account to continue. |
| 403 | Forbidden | Valid credentials but insufficient permissions for this resource. |
| 404 | Not Found | The requested resource doesn't exist. |
| 409 | Conflict | Operation conflicts with current resource state. |
| 422 | Unprocessable Entity | Request format is correct but cannot be processed. |
| 429 | Rate Limit Exceeded | Too many requests. Wait before retrying. |
| 500 | Internal Server Error | Unexpected server error. Retry after a brief wait. |
| 503 | Service Unavailable | Service temporarily down for maintenance or overloaded. Retry later. |
Best Practices
Build reliable applications with these error handling patterns:
- Catch specific errors first - Handle specialized error types before generic exceptions
- Check status codes early - Validate response status before processing the body
- Implement smart retries - Use exponential backoff for transient errors
Code Examples
Last updated: November 14, 2025