Transaction error codes
A list of all error codes for transactions.
A transaction's error_code value can be null (for successful transactions) or one of the following for failed and declined transactions.
Core failures
Our system can decline or fail a transaction, in contrast to a connector or payment service rejecting the transaction. When this happens, one of the following error codes can be set as the error_code value.
| error_code | Description |
|---|---|
incomplete_buyer_approval | Occurs when a buyer approval redirection times out, this normally means the buyer has closed the redirect page/popup without authenticating. This error code can take up to 10 minutes from the time the buyer closes the redirect page / popup to appear |
failed_buyer_approval | Occurs when a buyer fails to authenticate through 3DS. This transaction can be attempted again |
missing_redirect_url | Occurs when a transaction requires a redirect but was created without payment_method.redirect_url. Add the payment_method.redirect_url and retry |
flow_decline | Occurs when a transaction is declined by a Flow rule. This could be due to fraud or an alternate system configuration declining the transaction |
all_attempts_skipped | Occurs when a transaction fails because no outcome in the matched Flow rule can be used to process the transaction reliably. To avoid this, make sure to define there is a default suitable outcome for each possible transaction scenario |
Connector declines
When a payment service declines or fails the transaction the following error_code values can be set based on the response received from the payment service. The original values received from the payment service will be available in the raw_response_* fields of a transaction record.
The amount column in the tables below specifies the amount that can be used to simulate the error_code when using the Card simulator connector.
| error_code | Description | Simulator amount | Retriable? |
|---|---|---|---|
canceled_payment_method | The payment method reported lost, stolen, or otherwise canceled, request another payment method | 200001 | |
expired_authorization | The authorization has expired, create a new authorization and use the new one | 200004 | |
expired_payment_method | The payment method has expired, use another payment method | 200005 | |
incorrect_billing_address | The billing address does not match the account. Prompt the customer to correct the billing address and retry | 200006 | |
incorrect_country | The country code was rejected by the service or issuer, request another payment method | 200007 | Yes |
incorrect_currency | The currency code was rejected by the service or issuer, request another payment method | 200008 | Yes |
incorrect_cvv | The CVV was incorrect. Prompt the customer to correct the CVV and retry | 200009 | |
incorrect_expiry_date | The expiry date is incorrect or the payment method has expired. Prompt the customer to correct the expiry date and retry or request another payment method | 200010 | |
insufficient_funds | The amount exceeds the available balance on the payment method. Prompt the customer to check their balance | 200011 | |
issuer_decline | The payment was declined by the issuer. Prompt the customer to check with their issuer | 200012 | Yes |
other_decline | The transaction failed for an unknown reason, may succeed if retried | 200013 | Yes |
refused_transaction | The transaction was refused due to legal reasons (e.g. watch list, embargo, sanctions), request another payment method | 200015 | |
service_decline | The payment was declined by service, request another payment method | 200016 | Yes |
suspected_fraud | The service flagged the transaction as suspected fraud. Prompt the customer to check with their issuer | 200017 |
Connector failures
| error_code | Description | Simulator amount | Retriable? |
|---|---|---|---|
cancelled_buyer_approval | The transaction was canceled by the customer | 200022 | |
disputed_transaction | The transaction cannot be refunded as a chargeback has been initiated | 200002 | |
duplicate_transaction | The transaction is a duplicate of a previous transaction. Check to ensure the transaction was submitted only once | 200003 | |
insufficient_service_permissions | The service credentials lack permission to perform the requested action, check relevant configuration | 300001 | Yes |
invalid_amount | The amount not supported by service, check relevant configuration | 300002 | Yes |
invalid_payment_method | The payment method is not supported by the service (e.g. card scheme is not supported), request another payment method | 300003 | Yes |
invalid_service_configuration | The service is incorrectly configured, check relevant configuration | 300004 | Yes |
invalid_service_credentials | The service credentials are not valid, check relevant configuration | 300005 | |
invalid_service_response | The service response could not be parsed, check relevant configuration | 300006 | Yes |
invalid_tax_identifier | The tax identifier is invalid (e.g. GB VAT number is in an invalid format, or is of the wrong kind), correct identifier | 300007 | |
missing_billing_address | The billing address is required. Add billing address and retry | 300008 | Yes |
missing_cvv | The CVV is required. Add CVV and retry | 300009 | Yes |
missing_shipping_address | The shipping address is required. Add shipping address and retry | 300010 | Yes |
missing_tax_identifier | The tax identifier is required. Add tax identifier and retry | 300011 | Yes |
refund_period_expired | The refund can not be performed due to the refund period expiring, credit the customer in another way | 300012 | |
requires_buyer_authentication | Additional credentials were requested by the issuer, for example, the security code (CVV). Add these credentials and retry | 200014 | |
service_error | The service reported an internal server error or upstream processing error, check relevant configuration | 300013 | Yes |
service_network_error | The service was unreachable or experienced a timeout, wait before retrying | 300014 | Yes |
service_rate_limit | The service responded with a rate-limiting error, wait before retrying | 300015 | Yes |
internal_error | An internal error has occurred, check relevant configuration | 400001 | |
invalid_billing_address | The billing address is invalid. Correct billing address and retry | 400002 | |
invalid_operation | The service/method is not implemented, and operation is not supported for this request, check relevant configuration | 400003 | Yes |
invalid_request_parameters | The one or more request parameters are invalid, check payload and retry | 400004 | |
invalid_service_request | The service request could not be parsed, check payload and retry | 400005 | Yes |
invalid_shipping_address | The shipping address is invalid. Correct shipping address and retry | 400006 | |
service_resource_conflict | The service could not create a resource due to a conflict, check relevant configuration | 400007 | Yes |
unavailable_payment_method | The payment method is temporarily frozen or otherwise unavailable. Prompt the customer to check with their issuer or request another payment method | 200018 | |
unexpected_state | The service is configured in an unexpected state, check relevant configuration | 400008 | |
unknown_error | An unknown error occurred, check relevant configuration | 400009 | |
unknown_payment_method | The account is unknown, request another payment method | 200019 | Yes |
unknown_service_resource | The resource could not be found by the service, check relevant configuration | 400010 | Yes |
unrecognised_country | The country is not valid, correct the country and retry | 400013 | |
unrecognised_currency | The currency is not valid, correct the currency and retry | 400014 | |
unrecognised_payment_method | The payment method is not valid, request another payment method | 400015 | |
unrecognised_scheme | The payment scheme is not valid, request another payment method | 400016 | |
unsupported_country | The country is not supported by the service, correct country and retry | 400011 | Yes |
unsupported_currency | The currency is not supported by the service, correct currency and retry | 400012 | Yes |
unsupported_payment_method | The payment method is not supported by the service (e.g. card scheme is not supported), request another payment method | 200021 | |
unsupported_scheme | The payment scheme is not supported by the service, request another payment method | 400017 | |
unsupported_transaction | The payment method does not support this type of purchase (e.g. gambling is restricted), request another payment method | 200020 |
Connector Capture / Void / Refund / Payout tests
| error_code | Description | Simulator amount | Retriable? |
|---|---|---|---|
service_network_error | [Capture] The service was unreachable or experienced a timeout, wait before retrying | 500001 | |
refused_transaction | [Capture] The transaction was refused | 500002 | |
service_network_error | [Void] The service was unreachable or experienced a timeout, wait before retrying | 510001 | |
issuer_decline | [Void] The payment was declined by the issuer. Prompt the customer to check with their issuer | 510002 | |
disputed_transaction | [Refund] The transaction cannot be refunded as a chargeback has been initiated | 520001 | |
issuer_decline | [Refund] The payment was declined by the issuer. Prompt the customer to check with their issuer | 520002 | |
service_error | [Refund] The service reported an internal server error or upstream processing error | 520003 | |
service_decline | [Payout] The service declined the transaction | 530001 | |
service_error | [Payout] The service reported an internal server error or upstream processing error | 530002 |
Server-side errors (5XX)
In case of a server-side error in our system, our API will return an error with an HTTP status code in the 500 to 599 range.
None of these errors can be resolved client side. Please contact support to raise any 5XX errors.
Example
{
"type": "error",
"code": "server_error",
"status": 500,
"message": "Request could not be processed",
"details": []
}
Fields
type
string, required
The type of object returned. This is always error.
code
string, required
The machine-readable code for this error. This is one of the following values.
server_errorbad_gatewaygateway_timeout
status
number, required
The HTTP status code of the error. This can be 500, 502, or 504.
message
string, required
The human-readable description of this error.
details
array
A list of validation errors for the request. This is always an empty array for a server error.