Error handling and rate limits

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. The client library wraps the JSON response in an instance of APIException and throws the exception.

Note: Please use latest client library ( greater than 1.1.48 version) to make use of the upgraded error response. It enables simpler error handling. See the change notes for more details.

Sample error response 1:

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.

Sample error response 2:

Given below is a sample error response for the Create a subscription API call when a transaction fails at the gateway. The HTTP status code returned is 400.

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

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

Exception Classes

The client library throws specific exceptions based on the "type" attribute. You could have common error handling routines based on the exception type. For more specific error handling use the "api_error_code" attribute in the exception.

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.

Below is a sample pseudo code for handling errors in 'create subscription' api call. Let's assume that you are getting the card details along with coupon code from the user.

try{
  // The code calling ChargeBee_Subscription::create
  // ...
}catch(PaymentException ex){
  // First check for card parameters entered by the user.
  //We recommend you to validate the input at the client side itself to catch simple mistakes.
  if("card[number]".equals(ex.param)){
      // Ask your user to recheck the card number. A better way is to use 
      // Stripe's https://github.com/stripe/jquery.payment for validating it in the client side itself.   
  
  //}else if(<other card params>.equals(ex.param)){ 
      //Similarly check for card parameters entered by the user.
      //....

  }else{
    // Verfication or processing failures.
    // Provide a standard message to your user to recheck his card details or provide a different card.
    // Like  'Sorry,there was a problem when processing your card, please check the details and try again'. 
  }
}catch(InvalidRequestException ex){  
  // For coupons you could decide to provide specific messages by using 
  // the 'api_error_code' attribute in the error.
  if("coupon".equals(ex.param)){ 
      if("resource_not_found".equals(ex.apiErrorCode)){
          // Inform user to recheck his coupon code.
      }else if("resource_limit_exhausted".equals(ex.apiErrorCode)){
          // Inform user that the coupon code has expired.
      }else if("invalid_request".equals(ex.apiErrorCode)){
          // Inform user that the coupon code is not applicable for his plan(/addons).
      }else{
          // Inform user to recheck his coupon code.
      }
  }else{
      // Since you would have validated all other parameters on your side itself, 
      // this could probably be a bug in your code. Provide a generic message to your users.
  }
}catch(OperationFailedException ex){
  // Indicates that the request parameters were right but the request couldn't be completed.
  // The reasons might be "api_request_limit_exceeded" or could be due to an issue in ChargeBee side.
  // These should occur very rarely and mostly be of temporary nature. 
  // You could ask your user to retry after some time.
}catch(APIException ex){ 
  // Handle the other ChargeBee API errors. Mostly would be setup related 
  // exceptions such as authentication failure.
  // You could ask users contact your support.
}catch(IOException ex){
  // Handle IO exceptions such as connection timeout, request timeout etc.
  // You could give a generic message to the customer retry after some time.
}catch(Exception ex){
  // These are unhandled exceptions (Could be due to a bug in your code or very rarely in client library).
  // You could ask users contact your support.
}

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. These errors are thrown as PaymentException.

The following errors are caused due to invalid request. In most cases the errors should occur only during the development phase. These errors are thrown as InvalidRequestException.

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. These errors are thrown as OperationFailedException.

Most of these errors occur due to improper API environment setup in your server or changes to the site's configuration. These errors are thrown as APIException.

Exception Classes

The client library throws specific exceptions based on the "type" attribute. You could have common error handling routines based on the exception type. For more specific error handling use the "api_error_code" attribute in the exception.

Chargebee has robust and flexible API limits to serve a wide variety of business needs, when this limit is exceeded, you will see error messages with an HTTP status code of 429. The default limits are captured below.