Error Codes

Integrating with Switch

Here you can find codes and descriptions of all errors that may occur when you communicate with the Switch APIs.

If after reading this section you are still not sure how to interpret and solve a specific error, please contact our Support Team.

  • Error Code Format: XX.YY.ZZZZ (numeric)
  • 01.YY.ZZZZ: Validation Errors

    The request failed because there are issues with the data being sent.
  • 02.YY.ZZZZ: Soft Declines

    The request was declined. Yet, subsequent attempts may be successful.
  • 03.YY.ZZZZ: Hard Declines

    The request was declined. Most hard declines require the issuer or customer to rectify issues before a subsequent attempt can be made.
  • 04.YY.ZZZZ: Communication

    Problems in the communication between Switch and the processor. If these issues are recurring, it is important to check for the root cause.
  • 05.YY.ZZZZ: Implementation

    Errors raised when the integration with Switch was performed incorrectly.
  • 06.YY.ZZZZ: Risk

    Possible fraudulent activities.
  • 99.YY.ZZZZ: Unhandled Errors

    The request failed due to unspecified reasons. Further analysis might be needed.

Validation Errors

Error CodeDesignationDescription
01.01.0000Invalid ParametersRequest containing invalid parameters (e.g. email address).
01.02.0000Amount MismatchInvalid amount. The amount inputted does not match the request.
01.03.0000Instrument MismatchRequest containing invalid instrument details. The payment instrument used does not match the criteria set by the processor.

Soft Declines

Error CodeDesignationDescription
02.00.0001FailureFailure originated in the processor.
02.01.0000Too Many TriesYou have exceeded the maximum number of tries.
02.02.0000Limit ExceededThe customer exceeds the maximum allowed limit.
02.03.0000Insufficient FundsThere are not enough funds to complete this payment.
02.04.0000Temporary IssueThere is a temporary problem with your submission. Retry.

Hard Declines

Error CodeDesignationDescription
03.00.0001Processor DeclinedThe processor refused the transaction request.
03.00.0002Instrument ExpiredThe payment Instrument being used has expired.
03.01.0000Disabled AccountThe customer’s account has been disabled.
03.02.0000Unsupported ValueUnsupported value for this request. Review the content and retry.
03.02.0001Unsupported SchemeYour payment instrument does not support this type of purchase.
03.02.0002Unsupported BINUnsupported bank identification number.
03.03.0000Card is DeclinedThe transaction is refused by the issuer. Use a different card or contact your bank for further details.
03.03.0001Card is Flagged as Lost/Stolen/Expired/ RestrictedCard flagged as lost, stolen, expired, or restricted.
03.04.0000Duplicate OperationA transaction request with the same information has already been submitted.


Error CodeDesignationDescription
04.01.0000Processor UnavailableProcessor not available to confirm the transaction.
04.02.0000Timeout Communicating With ProcessorThe server took too long to respond. Check the status of the transaction. Retry if needed.


Error CodeDesignationDescription
05.01.0000Configuration ErrorChannel is not correctly configured.
05.02.0000Processor Configuration ErrorProcessor is not correctly configured.
05.01.0002Merchant Configuration ErrorMerchant account is not correctly configured in the processor.
05.02.0000Invalid Processor CredentialsThe credentials supplied do not grant access to the requested resource.
05.03.0000Authorization ErrorPermissions error.
05.03.0001Processor Authorization ErrorPermissions error coming from the processor.
05.03.0002Merchant Authorization ErrorAccess to resource denied. Verify your account permissions.
05.04.0000Feature Not AvailableFeature does not exist.
05.04.0001Instrument Already CapturedThe status of the instrument does not allow for your request (eg. reversing a card authorization that is already captured).
05.04.0002Instrument Not AuthorizedThe instrument verification does not allow for your request (eg. reversing a card authorization with 3DS that is still not authorized).


Error CodeDesignationDescription
06.00.0000Security RiskRisk declines that do not fit any other category.
06.01.00003DS ErrorProblems with the 3D Secure protocol.
06.01.00013DS Not Allowed3D Secure not supported.
06.01.00023DS Required3D Secure verification is required to complete your request.
06.02.0000Unsafe TransactionThis transaction has been flagged by the processor’s set of Risk rules.

Unhandled Errors

Error CodeDesignationDescription
99.00.0000Unspecified ErrorUnknown/unspecified errors that do not fit any other category.
99.01.0000Internal Server ErrorThe server encountered an internal error or misconfiguration and was unable to complete your request.
99.02.0000Processor Integration ErrorIssue(s) with the processor integration. Please contact our Support Team for further details.
99.02.0001Unexpected Processor ResponseProcessor response does not match the expected parameters. Please contact our Support Team for further details.
99.02.0002Unable To Read Processor ResponseProcessor response cannot be interpreted. Please contact our Support Team for further details.
99.02.0003Processor Resource Not FoundProcessor issued resources do not match the needs of your request. Please contact our Support Team.
99.02.0004Processor Unhandled ErrorThe request failed due to unspecified reasons. Issue not addressed by the processor. Please contact our Support Team.

Error Testing

Error handling is an important step in integration. To aid with error testing we have made triggering these errors a straightforward process. You only need to mind the amount set when you create a transaction.

In order to come up with the right amount to trigger the error you are looking for, mind the following instructions.

  • Amount: XZZZZ.YY (numeric);
  • The integer part of the amount represents the error code that will be returned. The decimal part of the amount represents the element from which the error originates (e.g. 0.10 for charge, 0.20 for instrument, 0.30 for payment, 0.40 for refund, 0.50 for reversal);
  • Do not include the "." separators and the leading "0"s in this number.


  • "amount": 6020000.20 Results in an instrument error (0.20), error code 06.02.0000.
  • "amount": 3030001.30 Results in a payment error (0.30), error code 03.03.0001.

Let’s use the first amount to exemplify the procedures involved in triggering an error. "amount": 6010000.20 Results in an instrument error (0.20), error code 06.01.0000.

$ curl -vX POST -u accountId:privateKey -d '{
"charge_type": "card_onetime",
"amount": 6020000.20,
"currency": "EUR",
"events_url": "",
"channels": ["card_onetime_no_processor"]

"amount": 6020000.20

All transactions begin with a charge. When creating this charge, you should input the amount that corresponds to the error you intend to trigger.

Additionally, you should note that the amount that defines the error is always the charge_amount, even if the current resource allows for a different amount to be set (e.g. payments, refunds).

"channels": ["card_onetime_no_processor"]

You should use a no_processor Switch channel for error testing. Channels result from a concatenation of the charge_type applied and the actual channel used for the transaction, hence the ["card_onetime_no_processor"] in this case. To gain access to this test channel and proceed with error testing you should contact our Support Department.

"id": "675d32208a91bd3ad70641ba7f810036c65f5bb75ea9897f",
"external_ids": null,
"charge_type": "card_onetime",
"charge_type_label": "Card One-Time",
"amount": 6020000.2,
"currency": "EUR",
"events_url": "",
"redirect_url": "",
"metadata": {},
"instrument_params": null,
"failure_code": null,
"failure_description": null,
"channels": [
"id": "d33577bcdc1ed9e106c050ff02bcccc285d57c5c5ea98619",
"label": "card_onetime_no_processor",
"processor": "no_processor"
"confirmed": true,
"created_at": "2020-04-29T14:04:47.145730+00:00",
"expires_at": null,
"updated_at": "2020-04-29T14:04:47.145770+00:00",
"request_log": {
"ip_address": "",
"country": "PT",
"user_agent": "PostmanRuntime/7.24.1",
"library_version": null
"external": false

The error we are triggering is generated in an instrument. Next, create an instrument deriving from the previous charge, using the correspondent charge_id.

"charge": "675d32208a91bd3ad70641ba7f810036c65f5bb75ea9897f",
"name": "John doe",
"number": "4111111111111111",
"expiration_month": 12,
"expiration_year": 2020,
"cvc": "007"

You should find the error in the response. In this case, we triggered a 06.02.0000: Unsafe Transaction. The respective instrument generated is invalid, as observable in the Switch Dashboard.

"message": "Transaction Error",
"metadata": {
"failure_description": null
"failure_description": "Unsafe Transaction",
"failure_code": "06.02.0000"

If after reading this section you are still not sure how to trigger a specific error, please contact our Support Department.