Package com.chargebee.v4.exceptions

Class APIException

java.lang.Object
java.lang.Throwable
java.lang.Exception
java.lang.RuntimeException
com.chargebee.v4.exceptions.ChargebeeException
com.chargebee.v4.exceptions.TransportException
com.chargebee.v4.exceptions.HttpException
com.chargebee.v4.exceptions.APIException
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
BatchAPIException, InvalidRequestException, OperationFailedException, PaymentException, UbbBatchIngestionInvalidRequestException
public class APIException extends HttpException
Base exception for all Chargebee API errors.

Contains parsed error information from the API response with the following attributes:

  • message - Descriptive information about the error (for developer consumption)
  • type - Groups errors based on error handling routine (payment, invalid_request, operation_failed)
  • api_error_code - Specific code for handling specific errors
  • param - The parameter name if error is due to a specific parameter
  • error_cause_id - Chargebee-defined code for standardizing errors across gateway services

Use getErrorType() for strongly-typed error type handling.

Example usage: 


 try {
     // API call
 } catch (InvalidRequestException e) {
     ErrorType type = e.getErrorType();
     ApiErrorCode errorCode = e.getApiErrorCode();
     List<String> invalidParams = e.getParams();
     String causeId = e.getErrorCauseId();

     // Type-safe error handling with enum
     if (errorCode instanceof BadRequestApiErrorCode) {
         BadRequestApiErrorCode code = (BadRequestApiErrorCode) errorCode;
         if (code == BadRequestApiErrorCode.DUPLICATE_ENTRY) {
             // Handle duplicate entry
         }
     }
 } catch (PaymentException e) {
     // Check error_cause_id for gateway-specific error handling
     if (e.getErrorCauseId() != null) {
         System.out.println("Gateway error cause: " + e.getErrorCauseId());
     }
 }
See Also:

  • Constructor Details

  • Method Details

    • getErrorType

      public ErrorType getErrorType()
      Get the error type as a strongly-typed enum. Use this for programmatic error handling with type safety.

      The type groups errors based on the error handling routine required:

      Returns:
      the error type enum, or ErrorType._UNKNOWN for unrecognized types

    • getType

      public String getType()
      Get the raw error type string as returned by the API. Use this when you need the exact API value or for logging.

      Possible values: "payment", "invalid_request", "operation_failed", or null

      Returns:
      the raw error type string, may be null

    • getApiErrorCode

      public ApiErrorCode getApiErrorCode()
      Get the API error code as a strongly-typed enum.

      The returned enum implements ApiErrorCode and can be cast to the specific enum type based on the HTTP status code: 

      
 ApiErrorCode code = e.getApiErrorCode();
 if (code instanceof BadRequestApiErrorCode) {
     BadRequestApiErrorCode badRequestCode = (BadRequestApiErrorCode) code;
     if (badRequestCode == BadRequestApiErrorCode.DUPLICATE_ENTRY) {
         // Handle duplicate
     }
 }
      Returns:
      the API error code as a typed enum

    • getApiErrorCodeRaw

      public String getApiErrorCodeRaw()
      Get the raw API error code string as returned by the API. Use this when you need the exact API value or for logging.
      Returns:
      the raw API error code string

    • getParams

      public List<String> getParams()
      Get the parameter name(s) that caused the error.

      This is provided when the error is due to a specific parameter. The parameter name matches the API documentation (cURL format).

      Note: For URL path parameters like customer_id, if invalid, a resource_not_found error is thrown without the param attribute.

      Returns:
      list of parameter names that caused the error, empty if not parameter-specific

    • getParam

      public String getParam()
      Get the first parameter name that caused the error. Convenience method when only one parameter is expected.
      Returns:
      the first parameter name, or null if no parameters

    • getErrorCauseId

      public String getErrorCauseId()
      Get the error cause ID - a Chargebee-defined code for standardizing errors across different gateway services.

      This helps in identifying and handling errors consistently across different payment gateways.

      Returns:
      the error cause ID, may be null if not applicable

    • getJsonResponse

      public String getJsonResponse()
      Get the full JSON response as string. Useful for debugging or extracting additional error details not covered by the typed fields.
      Returns:
      the full JSON error response

    • isRetryable

      public boolean isRetryable()
      API errors are generally not retryable as they indicate business logic issues.

      Exceptions that may warrant retry:

      • 429 Too Many Requests - Rate limiting
      • 5xx Server errors - Temporary server issues
      Overrides:
      isRetryable in class HttpException
      Returns:
      true only for 429 or 5xx status codes

    • toString

      public String toString()
      Overrides:
      toString in class HttpException