Transaction error codes

A transaction’s error_code value can be null (for successful transactions) or one of the following for failed and declined transactions.

Error codes and payment service responses

The error_code is a normalized category. Each connector maps the codes it receives from the payment service to one of the values on this page, so several different reasons from a payment service can share one error_code. For example, a decline because the card exceeded a spending limit and a decline because the account has too little money can both appear as insufficient_funds. To see the exact reason, for example to decide when to retry a payment, read the fields that carry the payment service’s own response. These fields are available on the transaction in the API and in the dashboard.

Field	Description
`raw_response_code`	The response code received from the payment service. It isn’t standardized across payment services.
`raw_response_description`	The response description received from the payment service. It isn’t standardized across payment services.
`auth_response_code`	The response code received from the processor.
`iso_response_code`	The ISO 8583 response code received from the payment service.
`merchant_advice_code`	The merchant advice code received from the payment service, which gives insight into the reason why the payment failed.

Not every payment service returns every field, so any of these fields can be null.

Merchant advice codes

Gr4vy passes the merchant_advice_code through as the payment service returns it. It isn’t normalized or mapped to another value. A transaction that returns a merchant advice code isn’t retried with another connection. When a stored card is declined with merchant advice code 01, the real-time account updater can check for updated card details. See the account updater for more information.

Core failures

The system can decline or fail a transaction itself rather than 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 the buyer doesn’t complete an approval step, such as 3-D Secure or a redirect to a payment page, before the transaction’s `approval_expires_at` time. This normally means the buyer closed the page or pop-up without authenticating. The approval window depends on the connection. When Gr4vy runs 3-D Secure itself, the payment is never sent to the payment service, so the payment service has no record of it. The dashboard shows this as 3DS incomplete
`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, for example, network token provisioning failed and no PAN outcome follows. To avoid this, make sure to define there is a default suitable outcome for each possible transaction scenario
`canceled`	Occurs when a transaction is canceled, this means a previously triggered cancel action has finished successfully
`timeout`	Occurs when the payment service doesn’t respond in time and Gr4vy can’t safely retry the request. The payment service may still have processed the payment, so check the payment at the payment service before you charge the buyer again. See timeouts

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 are available in the payment service 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.

The Retriable? column in the tables below only applies when the payment service returns no ISO 8583 response code. When an ISO response code is present, that code determines whether the transaction is retried, and the retriable ISO response codes list supersedes this column. A transaction is also never retried when the payment service explicitly marks the attempt as non-retriable, or when the response contains a merchant_advice_code.

`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 (for example 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 buyer canceled the payment at an approval or redirect step, for example, on a wallet or payment page. Not used when a bank or issuer stops a payment	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 (for example card scheme is not supported), request another payment method	300003	Yes
`invalid_service_configuration`	The service is incorrectly configured, check relevant configuration	300004
`invalid_service_credentials`	The service credentials are not valid, check relevant configuration	300005	Yes
`invalid_service_response`	The service response could not be parsed , check relevant configuration	300006	Yes
`invalid_tax_identifier`	The tax identifier is invalid (for example 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`	The issuer requested authentication or additional credentials, for example, 3-D Secure or the security code (CVV). Add these 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 (for example 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 (for example gambling is restricted), request another payment method	200020

Connector capture / void / refund / payout tests

`error_code`	Description	Simulator amount
`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
`refund_already_satisfied`	[Refund] The service reported that the transaction has already been fully refunded	520004
`service_decline`	[Payout] The service declined the transaction	530001
`service_error`	[Payout] The service reported an internal server error or upstream processing error	530002

Introduction

Transactions

Buyers

Checkout Sessions

Payment links

Payment options

Payouts

Refunds

Sessions

Settlement records

Disputes

Instruments

Vault

PSPs & Gateways

Errors

Other

Transaction error codes

Error codes and payment service responses

Merchant advice codes

Core failures

Connector declines

Connector failures

Connector capture / void / refund / payout tests

​Error codes and payment service responses

​Merchant advice codes

​Core failures

​Connector declines

​Connector failures

​Connector capture / void / refund / payout tests

Error codes and payment service responses

Merchant advice codes

Core failures

Connector declines

Connector failures

Connector capture / void / refund / payout tests