> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gr4vy.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 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.
## 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](/reference/transactions/get-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](/guides/features/account-updater/real-time) can check for updated card
details. See the [account updater](/guides/features/account-updater/overview) 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](/guides/api/statuses/transactions#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](#error-codes-and-payment-service-responses) 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](/guides/dashboard/flow/card-transactions#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 | 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 | |
| `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 | |
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.