Error Codes

Quickstart API
v1 API

Zuora uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a payment attempt failed, etc.). Codes in the 5xx range indicate an error with Zuora's servers.

Some 4xx errors that could be handled programmatically include an error code that briefly explains the error reported.

An error response contains the following attributes:

AttributeTypeDescription
typeenumType of the error. See the Error types section below for details.
codestringAn error code indicating the reported error. See the Error codes section below for details.
messagestringA human-readable message providing more details about the error.
parameterstringIf the error is parameter-specific, it shows the parameter related to the error. For example, you can use this attribute to display a message near the correct form field.

If the error is parameter-specific, the parameter related to the error. For example, you can use this to display a message near the correct form field.

HTTP status codes

The following table lists the HTTP status codes you might receiving when working with the Quickstart API:

HTTP status codeDescription
200 - OKEverything worked as expected.
201 - CreatedEverything worked as expected and a resource was created.
202 - AcceptedYour request has been accepted, but processing has not been completed and may not have been started.
400 - Bad RequestThe request contains invalid parameters.
401 - UnauthorizedThe request requires user authentication. Resend the request with valid authentication credentials for the resource.
403 - ForbiddenAccess is forbidden to users with your authentication credentials.
404 - Not FoundThe server cannot find the requested resource.
408 - Request TimeoutThe server has decided to close this connection rather than continue waiting.
409 - ConflictThe request conflicts with the current state of the target resource.
429 - Too Many RequestsToo many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 501, 502, 503, 504 - Server ErrorsSomething went wrong on Zuora’s end.

Error types

The following table lists values of the type field in the error response, and their corresponding description:
Error TypeDescription
bad_requestThe request contains invalid parameters.
unauthorizedThe request requires user authentication. Resend the request with valid authentication credentials for the resource.
forbiddenAccess is forbidden to users with your authentication credentials.
method_not_allowedThe server does not recognize the request method and is incapable of supporting it.
conflictThe request conflicts with the current state of the target resource.
not_foundThe server cannot find the requested resource.
lockedThis request cannot be processed because the objects this request is trying to modify are being modified by another process.
too_many_requestsToo many requests hit the API too quickly. We recommend an exponential backoff of your requests.
internal_server_errorSomething went wrong on Zuora’s end.
conflictThe request cannot be processed due to the violation of a Zuora business rule.
request_failedThe request failed because the payment gateway declines the transaction or a payment gateway error.
request_timeoutThe client connection has timed out.
gateway_timeoutTh host connection has timed out.
payment_gateway_timeoutThe payment gateway connection has timed out.
payment_gateway_unavailableThe payment gateway server is busy.
payment_gateway_errorGeneral transaction error.

Error codes

Some errors include an error code - a short string with a brief explanation.

Below is a list of possible error codes, along with additional information about how to resolve them.

Error codeDescription
invalid_parameterOne or more of the parameters requires a value of a specific type, but the values provided were a different type. Make sure that only supported values are provided for each attribute. Refer to our Quickstart API Reference to look up the type of data each attribute supports.
invalid_parameter_integerOne or more of the parameters requires an integer, but the values provided were a different type. Make sure that only support values are provided for each attribute. Refer to our Quickstart API Reference to look up the type of data each attribute supports.
invalid_parameter_numberOne or more of the parameters requires a number, but the values provided were a different type. Make sure that only support values are provided for each attribute. Refer to our Quickstart API Reference to look up the type of data each attribute supports.
invalid_parameter_booleanOne or more of the parameters requires a boolean, but the values provided were a different type. Make sure that only support values are provided for each attribute. Refer to our Quickstart API Reference to look up the type of data each attribute supports.
invalid_parameter_stringOne or more of the parameters requires a string, but the values provided were a different type. Make sure that only support values are provided for each attribute. Refer to our Quickstart API Reference to look up the type of data each attribute supports.
unknown_parameterThe request contains one or more unexpected parameters. Remove these parameters and try again.
missing_parameterOne or more required values are missing. Check our Quickstart API Reference to see which values are required to create or modify the specified resource.
parameters_exclusiveTwo or more mutually exclusive parameters were provided. Check our Quickstart API Reference or the returned error message to see which values are permitted when creating or modifying the specified resource.
invalid_requestThe request could not be understood by the server due to malformed syntax. Check our Quickstart API Reference to see how to create or modify the specified resource and modify your request accordingly.
not_foundThe requested resource does not exist.
card_errorAn error occurred while processing the card. Try again later or with a different payment method.
authorization_token_expiredThe authorization token provided has expired. Obtain a new authorization token and try again.
resource_not_foundThe resource identifier provided is not found.
Note: This error code applies to a resource referenced in a POST, PUT, or PATCH request. For example, when creating a payment method for an account by specifying either an account_number or account_id that does not exist. It will result in an error where the type is bad_request instead of not_found.
in_useThe resource cannot be deleted because it is being used.
invalid_valueThe values of one or more parameters you specified are invalid. Check the parameter values you specified, update them to valid values, then try again.
delete_not_allowedThe specified order cannot be deleted. This error is specific to the "Delete an order" operation.

Payment authorization errors

The following table summarizes the payment authorization error responses returned from the gateway, and the corresponding Zuora error information when you are making requests to the Create a payment authorization operation.

Authorization errorHTTP status codeError typeError codeParameter to check
1: The request is declined.402request_failedN/AN/A
7: The field format is not correct.400bad_requestN/AN/A
10: Client connection has timed out.408request_timeoutN/AN/A
11: Host connection has timed out.504gateway_timeoutN/AN/A
12: Processor connection has timed out.504payment_gateway_timeoutN/AN/A
13: Gateway server is busy.503payment_gateway_unavailableN/AN/A
20: The card type is not supported.409conflictunknown_card_typebrand
21: The merchant account information is invalid.400bad_requestincorrect_merchant_account_informationN/A
22: A generic error occurred on the processor.402request_failedgeneric_processor_errorN/A
40: The card type has not been set up yet.409conflictcard_type_not_enabledbrand
41: The limit for a single transaction is exceeded.402request_failedtransaction_limit_exceededamount
42: Address checking failed.402request_failedincorrect_addressaddress
43: Card security code checking failed.402request_failedincorrect_security_codesecurity_code
44: Failed due to the gateway security setting.402request_failedgateway_security_setting
45: Fraud protection is declined.402request_failedcard_declinedcard
46: Address checking or card security code checking failed (for Authorize.net gateway only).402request_failedincorrect_card_detailscard
47: The maximum amount is exceeded (for Authorize.net gateway only).402request_failedcard_limit_exceededN/A
48: The IP address is blocked by the gateway (for Authorize.net gateway only).402request_failedip_address_blockedip_address
49: Card security code checking failed (for Authorize.net gateway only).402request_failedincorrect_security_codesecurity_code
60: User authentication failed.402request_faileduser_authentication_failedN/A
61: The currency code is invalid.400bad_requestinvalid_currencycurrency
62: The transaction ID is invalid.400bad_requestincorrect_transaction_idauthorization_id
63: The credit card number is invalid.400bad_requestincorrect_card_numbercard_number
64: The card expiration date is invalid.400bad_requestincorrect_expiration_datecard
65: The transaction is duplicated.409conflictduplicate_transaction_idauthorization_id
66: Credit transaction error.402request_failedcredit_transaction_failedN/A
67: Void transaction error.402request_failedvoid_transaction_failedN/A
90: A valid amount is required.400bad_requestinvalid_amountamount
91: The BA code is invalid.400bad_requestN/AN/A
92: The account number is invalid.400bad_requestinvalid_account_numberbank_account_number
93: The ACH transaction is not accepted by the merchant.402request_failedach_transaction_not_acceptedN/A
94: An error occurred for the ACH transaction.402request_failedach_transaction_failedN/A
95: The version parameter is invalid.400bad_requestinvalid_versionN/A
96: The transaction type is invalid.400bad_requestinvalid_transaction_typeN/A
97: The transaction method is invalid.400bad_requestinvalid_transaction_methodN/A
98: The bank account type is invalid.400bad_requestinvalid_bank_account_typebank_account_type
99: The authorization code is invalid.400bad_requestincorrect_authorization_codeN/A
200: General transaction error.500payment_gateway_errorN/AN/A
500: The transaction is queued for submission.200OKN/AN/A
999: Unknown error.500internal_server_errorN/AN/A

Handling errors

If you use the Zuora SDK, use the following template to handle errors:

JavaNode
Copy
Copied
try {
  
  // Use Zuora's client library to make requests

} catch (RateLimitException e) {
  // Too many requests made to the API too quickly
} catch (InvalidRequestException e) {
  // Invalid parameters were supplied to Zuora's API
} catch (AuthenticationException e) {
  // Authentication with Zuora's API failed (maybe you changed API keys recently)
} catch (APIConnectionException e) {
  // Network communication with Zuora failed
} catch (ZuoraException e) {
  // Display a very generic error to the user, and maybe send yourself an email
} catch (Exception e) {
  // Something else happened, completely unrelated to Zuora
}
Copy
Copied
(async () => {
  try {

   // Use Zuora's client library to make requests
    
  }
  catch (error) {
     console.log(error);
  }
})();