API Version
Product Catalog
Library

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.

HTTP status codes are used to indicate success or failure of an API call. The body of the response contains the details of the error in JSON format.

Sample error response:

Given below is a sample error that is returned for the Create a subscription API call when the plan_id is invalid. The returned HTTP status code is 404.

{ "message":"Plan is not present", "type":"invalid_request" "api_error_code":"resource_not_found", "param":"item_id" }

HTTP Status Codes

The standard http status codes used are

  • 2XX The response code in this range implies the API call has succeeded.
  • 3XX This range is not used currently.
  • 4XX response codes indicate failure due to wrong input (i.e, client) side. As the usable list of http codes in the 4xx range is limited we predominantly use the 400 ( BAD REQUEST ) error code for client-side errors.
  • 5XX response codes indicate API request was valid but failed due to issues on the Chargebee server.

Error Attributes

The following attributes are returned as part of the error content.
message
A descriptive information about the error. This is for developer(/merchant) consumption and should not be used for showing errors to your customers.
type
An optional attribute which groups errors based on the error handling routine that is required. The types are payment, invalid_request and operation_failed. The client libraries throw a corresponding exception for easy error handling.
api_error_code
A more specific code allowing you to handle the specific errors.
param
An optional attribute which is provided if the error is due to a specific parameter. The parameter name is the same as that seen in this documentation when the language chosen is cURL.
Note: For the same API, customer_id is a URL path parameter. If that value is invalid, then an error of type = resource_not_found is thrown without the param attribute.

Note: There may be additional deprecated attributes (like error_code) which are present to support older versions of the libraries.

Error handling recommendations

API calls fail at the first error encountered by Chargebee while validating them. To enhance user experience, we recommend that you validate an API call thoroughly to avoid multiple failed attempts from your users, each time for a different error.

There are cases where you have to depend on Chargebee's validation for handling errors like coupon code validation or VAT validations. In such cases, check the specific param and api_error_code combination to show a proper error message to your users.

Handling API Throttling

If you receive an HTTP 429 Too Many Requests error response to an API call, it means that the API requests for your Chargebee site have exceeded acceptable limits. Chargebee may also send a Retry-After header indicating the time duration to wait before sending a new request. Follow these best practices:

  • If you see the Retry-After header, wait for the number of seconds indicated before retrying.
  • Use an exponential backoff algorithm when making further requests.
  • To prevent all your request threads/processes from retrying simultaneously (thundering herd problem), add some randomized jitter to the backoff algorithm to spread the requests out.

See Also: API Rate Limits.

The following are the list of codes grouped based on type.

Note: 'New' codes might get added (though additions are very rare). If you are handling for specific codes also ensure that there is a default block for handling unknown(/new) error codes.

These errors may occur when trying to store the payment method details(such as card, paypal, ACH etc) or when trying to collect a payment. These errors should be handled and appropriate message should be shown to the user. The type attribute in the error response is sent as payment.

Code
Description
payment_processing_failed
Returned when the payment collection fails.
HTTP Code: 400, Sample message: Subscription cannot be created as the payment collection failed. Gateway Error: Card declined.
payment_method_verification_failed
Returned when validation or verification fails for the provided payment method. For example if the payment method is card, this will include all card parameter validation errors and also verification failures from the gateway.
HTTP Code: 400, Sample message: Problem while adding the card. Error message : AVS check failed.
payment_method_not_present
Returned when the request requires payment collection but the 'payment method' details (such as card) is not present for the customer. This error will not occur if auto-collection is disabled for the customer.
HTTP Code: 400, Sample message: Card is not present when reactivating the subscription
payment_gateway_currency_incompatible
Returned when the payment gateway configured is incompatible with the transactional currency. This error will not occur if auto-collection is disabled for the customer.
HTTP Code: 400, Sample message: The configured gateway account [ PAYPAL_EXPRESS_CHECKOUT ] does not support transactions in INR.
payment_intent_invalid
Returned when validation or verification fails for provided payment intent.For example if payment intent which is passed is in not consumable state.
HTTP Code: 400, Sample message: Problem while processing payment intent. Probable Reason: Invalid state
payment_intent_invalid_amount
Returned when processing amount is different from payment intent amountFor example if payment intent which is passed has authorized 10$ and if the charges initiated is for 12$.
HTTP Code: 400, Sample message: Problem while processing payment intent . Probable Reason: amount mismatch

The following errors are caused due to invalid request. In most cases the errors should occur only during the development phase. The type attribute in the error response is sent as invalid_request.

Code
Description
resource_not_found
Returned when any of resource(s) referred in the request is not found.
HTTP Code: 404, Sample message: 82sa2Sqa5 not found
resource_limit_exhausted
Returned when any limit constraint is violated by the request. For example this error is thrown when the coupon provided has already expired or its maximum redemption count has been reached.
HTTP Code: 400, Sample message: Coupon has expired
param_wrong_value
Returned when the value does not meet the required specification for the parameter. For example, wrong email format. It is strongly recommended to do the validation at your end before calling Chargebee's API (other than specific cases like VAT number validation).
HTTP Code: 400, Sample message: invalid email format
duplicate_entry
Returned when the request provides a duplicate value for an attribute that is specified as unique for that site. For example in 'create subscription api' if you are passing the subscription id then this error will be thrown if a subscription exists in site with the same id.
HTTP Code: 400, Sample message: The value Hy5r4129u is already present.
db_connection_failure
Returned when db connection fails.
HTTP Code: 503, Sample message: Sorry, unable to complete the operation due to db communication failure. Please try after some time
invalid_state_for_request
Returned when the requested operation is not allowed for current state of the resource. This error will occur if the state of the resource has not been checked for the validity of the request. For example this error is returned when we try to schedule subscription changes at 'end of term' for canceled subscriptions.
HTTP Code: 409, Sample message: Only pending invoices can be closed.
http_method_not_supported
Returned when the 'http method', specified in the request, is not allowed for this URL. It should not occur if you are using one of the standard client library.
HTTP Code: 405, Sample message: Sorry,the http method GET is not supported for this URL.
invalid_request
Returned when the request has incompatible values or does not match the API specification. As it is a generic error, handling this error is recommended only in combination with param attribute.
HTTP Code: 400, Sample message: The plan's billing period and addon's billing period are incompatible.
resource_limit_exceeded

HTTP Code: 400, Sample message:
unable_to_process_request
Returned when the HTTP request body contains a well-formed, but semantically erroneous payload. For example this error is returned when a client attempts to reuse an idempotency key with a different request payload.
HTTP Code: 422, Sample message: Unable to process the request due to semantic errors.

These errors are returned when the request was valid but the requested operation could not be completed. These errors should occur very rarely. You generally need not handle them specifically other than showing a generic error message to your users. The type attribute in the error response is sent as operation_failed.

Code
Description
lock_timeout
Returned when there are multiple concurrent requests to the same resource.
HTTP Code: 429, Sample message: The request cannot be processed right now as another API request or process is currently accessing the same resource. Please retry.
internal_error
Returned when the request parameters were right but the operation couldn't be completed due to a bug in Chargebee side.
HTTP Code: 500, Sample message: Sorry,Something went wrong when trying to process the request.
internal_temporary_error
Returned when temporary occured in Chargebee side. The request can be re-tried, with exponential backoff in case of repeat failures.
HTTP Code: 503, Sample message: Sorry,A temporary error occured when trying to process the request.
request_blocked
Returned when request is blocked for your site. The blocking could be only for a specific set of operation(s) . The reason would be provided as part of the message. You would have to contact support for additional details.
HTTP Code: 403, Sample message: Sorry, The request is blocked
api_request_limit_exceeded
Returned when requests have been blocked temporarily due to request count exceeding acceptable limits.
HTTP Code: 429, Sample message: Sorry, access has been blocked temporarily due to request count exceeding acceptable limits. Please try after some time.
third_party_api_request_limit_exceeded
Returned when your request is blocked temporarily at a third-party service, due to the request count exceeding their acceptable limits.
HTTP Code: 429, Sample message: Sorry, access has been blocked temporarily at a third-party service, due to the request count exceeding their acceptable limits. Please try after some time.
site_not_ready
Returned when your site is temporarily unavailable due to a scheduled maintenance.
HTTP Code: 503, Sample message: Site is not ready. Please retry the request after sometime.
site_read_only_mode
Returned when your site is temporarily unavailable for write operations due to a scheduled maintenance.
HTTP Code: 503, Sample message: Site is in read only mode. Please retry the request after sometime.

Most of these errors occur due to improper API environment setup in your server or changes to the site's configuration. The type attribute is not sent in the error response.

Code
Description
api_authentication_failed
Returned when authentication failed for the request. The possible reasons could be the api key is invalid or authentication header is not present in the request or the header's format is invalid.
HTTP Code: 401, Sample message: Sorry, authentication failed. Invalid API Key.
basic_authentication_failed
Returned when authentication failed for the request. The possible reasons could be that one or both of the username and password are invalid
HTTP Code: 401, Sample message:
api_authorization_failed
Returned when the API key does not have sufficient privileges to perform the particular operation.
HTTP Code: 403, Sample message: Sorry, authorization failed. The key does not have the required permissions
site_not_found
Returned when the site is not found.
HTTP Code: 404, Sample message: Sorry, we couldn't find the site acme
configuration_incompatible
Returned when the request is not compatible with the configuration for the site or the configuration is incomplete.
HTTP Code: 400, Sample message: Return URL for the hosted page not configured.

Chargebee restricts API requests when you exceed the limits entitled for your plan. The limiting mechanism is employed considering two criteria:

  • Requests per minute - Number of requests in the past 60 seconds.
  • Concurrent requests - Number of requests at an instance of time.
Thresholds set for both test and live sites are as follows:
  • Test sites: ~750 API calls per every 5 minutes
  • Live sites: ~150 API calls per site per minute

When the upper limit is breached on either of the above criteria, an HTTP 429 error response is returned for subsequent requests. As a result, no more requests are served until the limit resets (in approximately a minute). For more details about error 429, refer to api_request_limit_exceeded in Error Codes List.

Please note that a cooling period is set for both test and live sites:

  • For test sites: five minutes from the time error 429 is thrown
  • For live sites: one minute from the time error 429 is thrown
You must wait until the cooling period expires before making another API call. In addition, to avoid the 429 error, it is recommended that you separate each API request by at least one second.

If you need a temporary rate limit increase, contact Chargebee Support to have it increased. Furthermore, if you exceed your limit frequently, you should consider upgrading to a higher plan in order to accommodate the increase of your API request volume.

Listed below are the API rate limits for each Chargebee plan:

PLAN   REQUESTS PER MINUTE LIMIT  CONCURRENT REQUESTS LIMIT  
 Live site  Test site   Live site   Test site 
 Starter  150  150 Up to 150 simultaneous requests, of which GET requests should not exceed 50 and POST requests should not exceed 100. Up to 100 simultaneous requests, of which the GET and POST requests must not exceed 50 each.    
 Performance 300 
 Enterprise  500 
Concurrency limitations

Concurrent POST requests to an API resource are not permitted. Always make POST requests to a resource in sequence or the API returns a lock_timeout error.

For example:

  • You cannot make parallel requests to estimate creating a subscription for the same customer; you must make them in sequence. However, you can make such requests in parallel for different customers.
  • Similarly, you cannot pause a subscription while also updating the same subscription. Nonetheless, you can pause one subscription while updating another in parallel.