Error handling and rate limits
Chargebee API provides error handling capabilities by using standard HTTP error codes and additional helpful parameters in its error responses. This page provides recommendations on effective error handling and a reference for all custom and standard error codes used by the API.
Error codes
Chargebee uses conventional HTTP response codes to indicate the success or failure of an API request. In general:
- 2xx codes indicate success
- 4xx codes indicate an error that failed given the information provided (e.g., a required parameter was omitted)
- 5xx codes indicate an error with Chargebee's servers
Common error codes:
| Code | Description |
|---|---|
| 200 | OK - Request succeeded |
| 400 | Bad Request - The request was invalid or cannot be served |
| 401 | Unauthorized - Authentication failed or not provided |
| 402 | Payment Required - Parameters were valid but request failed |
| 404 | Not Found - The requested resource doesn't exist |
| 429 | Too Many Requests - Rate limit exceeded |
| 500, 502, 503, 504 | Server Errors - Something went wrong on Chargebee's end |
Rate limits
To ensure stability and fair usage, Chargebee enforces rate limits on API requests. When you exceed the rate limit, you'll receive a 429 Too Many Requests response.
Best practices for handling rate limits:
- Implement exponential backoff for retries
- Cache responses when possible
- Spread API calls over time
- Monitor rate limit headers in responses
Contact Chargebee support if you need higher rate limits for your integration.