API DocsDocs

Decline Codes Reference Guide

19 min readUpdated Sep 9, 2025

This guide provides a list of common decline and error codes encountered on the Exirom platform. These codes help technical users and developers understand why a transaction was declined or an error occurred. Each code has a brief description in simple terms. The codes are grouped into key categories for easier reference.

#Quick Reference: What To Do

ActionCodesWhat You Should Do
Retry the transaction1, 9, 12, 13, 61, 63, 70, 72, 73, 702, 1010, 1023, 3001, 3021Transient errors. Retry with same requestId, exponential backoff (2s, 4s, 8s). Max 3 retries.
Fix merchant-side issue8, 14, 17, 24–27, 30, 31, 65, 103, 105, 201–205, 502, 908, 909, 1011–1018, 3016, 3017, 3020, 3022, 4002, 4005, 4022, 4023, 4028, 20954Check your request payload. Fix the data and resubmit with a new requestId. Do not auto-retry.
Customer action needed3–6, 10, 19–23, 33, 34, 100, 104, 300–317, 500, 501, 700, 900–907, 910–915, 1001–1006, 1019–1022, 1024, 1025Show a user-friendly message. Do not auto-retry — let the customer try again.
Contact Exirom support7, 28, 29, 32, 62, 64, 66–69, 78, 101, 102, 400–404, 600–603, 701, 800, 801, 1000, 1007, 1008, 3008–3012, 3014, 3015, 4001, 4009–4012, 4015, 4016, 4024, 4025, 4032, 7777, 19991Include transactionId and traceId in your support ticket. Do not retry.

#Customer-Facing Messages by Code

Use these messages (or similar) to guide customers when their payment fails:

CodeCustomer Message
3, 10, 19–23"3D Secure verification failed. Please try again and complete the verification step."
4, 9"Your session expired. Please try again."
5, 33, 34"Insufficient funds. Please use a different card or top up your account."
6"Your bank declined this transaction due to spending limits. Contact your bank or use another card."
2, 11, 32, 75, 76, 82"Your card was declined. Please try a different card or contact your bank."
79"Your card has expired. Please use a different card."
1, 12, 13, 70, 72, 73"Something went wrong. Please try again in a moment."

For a complete guide on retry logic and error recovery patterns, see the Error Recovery Patterns guide.

#Upstream Decline Codes

Upstream decline codes indicate issues reported by the issuing bank or payment gateway during processing. Common upstream codes include those for insufficient funds, fraud detection, 3-D Secure (3DS) errors, and technical failures.

CodeCode NameDescription
1UNEXPECTED_ERRORA generic or unknown error occurred.
2REJECTED_BY_ISSUER_BANK_ERRORThe issuer bank rejected the transaction.
3THREE_DS_AUTHENTICATION_ERRORAn error occurred during 3‑D Secure authentication.
4FORM_TIMEOUT_ERRORThe payment form session timed out or expired.
5INSUFFICIENT_FUNDS_ERRORThe account or card has insufficient funds.
6LIMITED_BY_ISSUER_BANK_ERRORThe issuer bank’s limit prevented the transaction.
7ANTI_FRAUD_ERRORFlagged as fraudulent by the anti-fraud system.
8DATA_VALIDATION_ERRORProvided payment/card data failed validation checks.
9PREPAY_TIMEOUT_ERRORA timeout occurred during the pre-payment process.
10THREE_DS_PAGE_ERRORThe 3‑D Secure page encountered an error and halted.
11PROCESSOR_DENIEDThe payment processor denied the transaction.
12GENERIC_PROCESSING_ERRORA generic error occurred during processing.
13TECHNICAL_GATEWAY_ERRORA technical error occurred at the payment gateway.
14DUPLICATED_ORDER_ID_ERRORThe provided order ID is already in use (duplicate order).
15CURRENCY_EXCHANGE_NOT_ALLOWED_ERRORCurrency conversion is not permitted for this transaction.
16GATE_NOT_FOUND_ERRORThe specified payment gateway or channel was not found.
17ORDER_BILLING_ERRORThere was an error in the order’s billing details.
18CARD_TIME_LIMIT_ERRORThe allowable time window for the card transaction was exceeded.
19THREE_DS_TIMEOUT_ERRORThe 3‑D Secure process timed out.
20THREE_DS_CANCEL_ERRORThe 3‑D Secure process was canceled by the user or system.
21THREE_DS_REDIRECT_TIMEOUTThe 3‑D Secure redirect process timed out.
22THREE_DS_REDIRECT_ERRORAn error occurred during the 3‑D Secure redirect.
23THREE_DS_ABANDONEDThe 3‑D Secure process was abandoned before completion.
24CARD_INFORMATION_INVALIDThe card details provided are invalid.
25INVALID_CUSTOMER_REDIRECT_URLThe customer redirect URL provided is invalid.
26INVALID_CALLBACK_URLThe callback URL provided is invalid.
27CURRENCY_NOT_SUPPORTEDThe selected currency is not supported for this transaction.
28FRAUDULENT_TRANSACTIONThe transaction was flagged as fraudulent and rejected.
29MERCHANT_NOT_ACTIVEThe merchant account is inactive or disabled.
30INVALID_CARD_HOLDER_DETAILSCardholder details are incorrect or missing.
31INVALID_ORDER_AMOUNTThe order amount is invalid or not allowed.
32PSP_GENERAL_DECLINEThe PSP declined the transaction for an unspecified reason.
33ACCOUNT_EMPTY_BALANCEThe payout account has zero balance.
34ACCOUNT_INSUFFICIENT_BALANCEThe payout account has insufficient balance for this transaction.
61INTERNAL_UNEXPECTED_ERRORAn unknown error occurred in the internal system.
62INTERNAL_VALIDATION_ERRORThe internal system failed a validation check.
63GATEWAY_UNEXPECTED_ERRORAn unknown error occurred at the gateway.
64GATEWAY_ANTI_FRAUD_ERRORFlagged as fraudulent by the gateway’s anti-fraud system.
65GATEWAY_VALIDATION_ERRORData failed validation checks at the gateway.
66GATEWAY_FX_CONVERSION_ERRORAn error occurred during currency conversion at the gateway.
67GATEWAY_NO_DOWNSTREAM_GATEWAY_ERRORNo downstream gateway was available to route the request.
68GATEWAY_DOWNSTREAM_GATEWAY_ERRORThe downstream payment provider returned an error.
69GATEWAY_TRANSACTION_LIMIT_ERRORA gateway-imposed transaction limit blocked the request.
70GATEWAY_PROCESSING_ERRORA generic error occurred during gateway processing.
71GATEWAY_AUTHENTICATION_ERRORAn authentication error occurred at the gateway.
72GATEWAY_TECHNICAL_ERRORA technical issue occurred at the gateway.
73GATEWAY_TIMEOUT_ERRORThe gateway timed out while processing the transaction.
74GATEWAY_INSUFFICIENT_FUNDSThe gateway reported insufficient funds.
75GATEWAY_CARD_DECLINEDThe gateway declined the card transaction.
76GATEWAY_ISSUER_DECLINEDThe card issuer (via gateway) declined the transaction.
77GATEWAY_DUPLICATE_REQUESTA duplicate transaction request was detected by the gateway.
78GATEWAY_POLICY_VIOLATIONThe transaction violated a gateway policy.
79GATEWAY_CARD_EXPIREDThe card has expired.
80GATEWAY_REDIRECT_ERRORAn error occurred during a gateway redirect.
81GATEWAY_LIMIT_EXCEEDEDA gateway limit (threshold) was exceeded.
82GATEWAY_GENERAL_DECLINEThe transaction was declined by the gateway for an unspecified reason.

#Country Declines

Country-based declines occur when the customer's country fails the merchant's country routing rules (allowlist, blocklist, or origin-type constraints).

CodeCode NameDescription
100COUNTRY_CODE_IS_BLOCKEDThe customer's country is on the merchant's blocklist.
101COUNTRY_ORIGIN_TYPE_NOT_SUPPORTEDThe country origin type (billing, IP, etc.) is not supported by the routing configuration.
102COUNTRY_RESTRICTION_MODE_NOT_SUPPORTEDThe country restriction mode is not supported.
103COUNTRY_CODE_IS_MISSING_WHEN_NOT_OPEN_ALLCountry code is required but missing from the request.
104COUNTRY_CODE_IS_NOT_ALLOWThe customer's country is not in the merchant's allowed list.
105MULTIPLE_COUNTRIES_DETECTEDConflicting countries detected across billing / IP / card BIN.

#Domain & Redirect Declines

These errors relate to HTTP Referer validation and redirect URL constraints configured on the merchant account.

CodeCode NameDescription
201DOMAIN_NOT_ALLOWEDThe request domain constraint blocked the transaction.
202DOMAIN_REFERER_MISSING_OR_EMPTYThe HTTP Referer header is missing or empty while a domain constraint is active.
203DOMAIN_REFERER_INVALID_FORMATThe HTTP Referer header has an invalid format.
204DOMAIN_REFERER_NOT_IN_ALLOWED_LISTThe HTTP Referer is not in the merchant's allowed domains list.
205REDIRECT_URL_DECLINEDThe provided redirect URL failed validation.

#Risk Declines

Risk declines are raised by the Exirom risk engine based on configured rules. They evaluate signals such as AVS, CVV, device, email, shipping/billing, IP location, etc.

CodeCode NameDescription
300RISK_OVERALL_DECLINEDDeclined by the overall risk score / rule.
301RISK_AVS_DECLINEDDeclined by AVS (Address Verification System) check.
302RISK_BILLING_ADDRESS_DECLINEDBilling address failed risk check.
303RISK_BROWSER_DECLINEDBrowser fingerprint failed risk check.
304RISK_CHARGEBACK_DECLINEDDeclined due to prior chargeback history.
305RISK_COUNTRY_DECLINEDCountry failed risk-rule check.
306RISK_COUNTRY_MISMATCH_DECLINEDCountry mismatch detected (e.g., billing vs. IP).
307RISK_CVV_DECLINEDCVV check failed.
308RISK_DEVICE_DECLINEDDevice failed risk check.
309RISK_EMAIL_ADDRESS_DECLINEDEmail address failed risk check.
310RISK_EMAIL_DOMAIN_DECLINEDEmail domain failed risk check.
311RISK_EMAIL_LOCAL_PART_DECLINEDEmail local part failed risk check.
312RISK_ISSUER_ID_NUMBER_DECLINEDCard issuer ID number (BIN) failed risk check.
313RISK_ORDER_AMOUNT_DECLINEDOrder amount failed risk check.
314RISK_PHONE_NUMBER_DECLINEDPhone number failed risk check.
315RISK_SHIPPING_ADDRESS_DECLINEDShipping address failed risk check.
316RISK_SHIPPING_ADDRESS_DISTANCE_TO_IP_LOCATION_DECLINEDShipping address is too far from the IP geolocation.
317RISK_TIME_OF_DAY_DECLINEDTransaction blocked by a time-of-day risk rule.

#Activable Decline Codes

Activable decline codes relate to account or configuration activation status. These errors occur if a required account or route is inactive or not properly set up.

CodeDescription
400The merchant account is inactive (the merchant’s account is not active/enabled).
401Account is inactive (the specific account or sub-account is not active).
402External MID is inactive (the external merchant ID/account is not active).
403Entity activation status undefined (the activation state of a required entity is not set).
404Could not route transaction to upstream (no active route to any upstream processor).

#First-Time Deposit (FTD) Declines

FTD declines are raised by first-time-deposit rules — typically requiring an existing successful transaction history or specific data for the customer's first deposit.

CodeCode NameDescription
500FTD_CONSTRAINT_DECLINEDThe first-time-deposit constraint blocked the transaction.
501FTD_NOT_ENOUGH_SUCCESS_TRANSACTIONSThe customer does not have enough successful transactions to bypass the FTD rule.
502FTD_VALIDATION_FAILED_MISSING_DATAFTD validation failed — required data was missing in the request.

#FX Conversion Declines

FX declines are raised when currency conversion fails or is not allowed by the merchant account configuration.

CodeCode NameDescription
600FX_CONVERSION_RATE_MISSINGNo FX rate available for the requested currency pair.
601FX_CONVERSION_MERCHANT_ACCOUNT_NOT_SUPPORTEDFX conversion is not supported on the selected merchant account.
602FX_CONVERSION_ERRORAn error occurred during FX conversion.
603FX_PAYOUT_CONVERSION_MERCHANT_ACCOUNT_NOT_ALLOWEDFX conversion on payouts is not allowed for this merchant account.

#Blacklist Declines

Blacklist declines are raised when the transaction or any of its attributes match an entry on the merchant's (or platform's) blacklist.

CodeCode NameDescription
700BLACKLIST_VALIDATION_DECLINEDBlacklist check matched — transaction blocked.
701BLACKLIST_VALIDATION_FAILEDBlacklist validation failed (technical error).
702BLACKLIST_CHECK_TIMEOUTBlacklist check timed out.

#Card Network Declines

Card network declines occur when the card brand (Visa/MC/Amex/etc.) is not enabled on the merchant or routing target.

CodeCode NameDescription
800NON_SUPPORTED_CARD_NETWORKThe card network/brand is not supported for this transaction.
801MERCHANT_ACCOUNT_HAS_NO_SUPPORTED_CARD_NETWORKS_COUNTThe merchant account has no enabled card networks.

#Limit / Counter Declines

Limit declines are raised when a transaction would exceed a configured daily/monthly limit (count or volume) on the merchant, account, card, or customer level.

CodeCode NameDescription
900DAILY_MAX_TRX_COUNT_DECLINEDDaily maximum transaction count reached on the merchant/account.
901DAILY_MAX_VOLUME_DECLINEDDaily maximum transaction volume reached.
902MONTHLY_MAX_TRX_COUNT_DECLINEDMonthly maximum transaction count reached.
903MONTHLY_MAX_VOLUME_DECLINEDMonthly maximum transaction volume reached.
904DAILY_MAX_CARD_TRX_COUNT_DECLINEDDaily maximum count of transactions for this card reached.
905DAILY_MAX_CARD_VOLUME_DECLINEDDaily maximum volume for this card reached.
906MONTHLY_MAX_CARD_TRX_COUNT_DECLINEDMonthly maximum count of transactions for this card reached.
907MONTHLY_MAX_CARD_VOLUME_DECLINEDMonthly maximum volume for this card reached.
908TRANSACTION_MIN_AMOUNT_DECLINEDTransaction is below the minimum allowed amount.
909TRANSACTION_MAX_AMOUNT_DECLINEDTransaction is above the maximum allowed amount.
910CUSTOMER_DAILY_MAX_TRX_COUNT_DECLINEDDaily maximum transaction count for the customer reached.
911CUSTOMER_MONTHLY_MAX_TRX_COUNT_DECLINEDMonthly maximum transaction count for the customer reached.
912CUSTOMER_DAILY_MAX_VOLUME_DECLINEDDaily maximum transaction volume for the customer reached.
913CUSTOMER_MONTHLY_MAX_VOLUME_DECLINEDMonthly maximum transaction volume for the customer reached.
914DAILY_MAX_CARD_FAILED_TRX_COUNT_DECLINEDDaily maximum count of failed transactions for this card reached.
915DAILY_MAX_CUSTOMER_FAILED_TRX_COUNT_DECLINEDDaily maximum count of failed transactions for the customer reached.

#3DS Authentication Declines

These codes are raised by the Exirom orchestration layer when 3-D Secure authentication fails. They are more granular than the upstream codes (3, 10, 19–23).

CodeCode NameDescription
1001AUTHENTICATION_FAILED3DS authentication failed.
1002AUTHENTICATION_FAILED_TIMEOUT3DS authentication timed out.
1003AUTHENTICATION_FAILED_INVALID_RESPONSE3DS authentication returned an invalid response.
1004AUTHENTICATION_FAILED_ABORTED_BY_USER3DS authentication was aborted by the user.
1005AUTHENTICATION_FAILED_ABORTED_BY_ISSUER3DS authentication was aborted by the issuer.
1006AUTHENTICATION_FAILED_ABANDONED_BY_USER3DS authentication was abandoned by the user.
1007THREE_DS_REDIRECT_ERRORError during 3DS redirect flow.
1008THREE_DS_REDIRECT_TIMEOUT3DS redirect flow timed out.

#Failed Sub-Reasons

Failed sub-reasons give a more specific reason for a downstream decline. They surface in addition to the broader upstream code so you can apply finer-grained retry / customer-message logic.

CodeCode NameDescription
1010DOWNSTREAM_TIMEOUTDownstream PSP did not respond in time.
1011DECLINED_INVALID_CVVDeclined — invalid CVV.
1012DECLINED_INVALID_EXPIRY_DATEDeclined — invalid card expiry date.
1013DECLINED_INVALID_CARD_NUMBERDeclined — invalid card number.
1014DECLINED_INVALID_AMOUNTDeclined — invalid amount.
1015DECLINED_INVALID_CURRENCYDeclined — invalid or unsupported currency.
1016DECLINED_INVALID_MERCHANTDeclined — invalid merchant.
1017DECLINED_INVALID_TRANSACTIONDeclined — invalid transaction.
1018DECLINED_UNSUPPORTED_BRANDDeclined — unsupported card brand.
1019DECLINED_LIMIT_EXCEEDEDDeclined — limit exceeded at the issuer/processor.
1020DECLINED_SUSPECTED_FRAUDDeclined — suspected fraud.
1021DECLINED_DO_NOT_HONORDeclined — generic "do not honor" from the issuer.
1022DECLINED_BY_BINDeclined — blocked by BIN rule.
1023DECLINED_BY_COMMUNICATION_ERRORDeclined — communication error with the processor.
1024DECLINED_BY_BIN_CHECK_FAILEDDeclined — BIN check failed.
1025ABANDONED_TX_RISK_CHECK_DECLINEDAbandoned-transaction risk check declined the request.

#Business / Orchestration Errors

These errors indicate system-level issues with the request (missing transaction, invalid state, duplicate request, configuration not found, etc.). Most are transient and may resolve on retry, but several indicate a misconfigured or invalid request and require a fix on your side.

CodeCode NameDescription
1000NO_PROCESSOR_AVAILABLENo payment processor was available to handle the request.
3001Downstream service timeoutAn external service did not respond in time.
3008PSP_ID_NOT_FOUND_ON_ROUTING_STAGEThe PSP could not be resolved at the routing stage.
3009EXTERNAL_MID_NOT_FOUND_ON_ROUTING_STAGEExternal MID could not be resolved at the routing stage.
3010PROCESSORS_NOT_AVAILABLENo payment processors were available to handle the request.
3011BIN_CHECK_RESULT_NOT_FOUNDBIN check result was not found.
3012PAYMENT_TX_NOT_FOUND_FOR_REFUNDThe payment transaction referenced for the refund does not exist.
3014MERCHANT_REDIRECT_ALLOWED_HOST_ERRORThe merchant's redirect host validation failed.
3015APM_SERVICE_NOT_FOUNDNo APM service was found for this transaction.
3016INVALID_USER_TOKENThe user token in the request is invalid or expired.
3017SUCCEEDED_REFUND_ALREADY_EXISTSA successful refund already exists for this payment.
3020INVALID_INTENT_STATUSThe payment intent is in an invalid status for this operation.
3021DECLINED_TIMEOUT_NO_PSP_RESPONSEDeclined — no response was received from the PSP within the timeout window.
3022INVALID_APPLE_PAY_SESSION_REQUESTThe Apple Pay session request is invalid.

#Routing Declines

Routing declines occur when Exirom cannot resolve a route to an upstream processor — typically because no routing condition matched, no route was assigned, or routing configuration is missing. Related routing codes also appear as 404 and 3008–3010. These indicate a configuration issue — do not retry; contact Exirom support.

CodeCode NameDescription
4009NO_PENDING_CASCADING_STEP_FOUNDNo further cascading step was available to route the transaction.
4010NO_ROOT_NODE_FOUNDThe routing configuration has no root node defined.
4011NO_MATCH_ROUTE_CONDITION_NOR_DEFAULT_NODENo routing condition matched and no default route is configured.
4012NO_ROUTING_CONFIG_FOUNDNo routing configuration was found for this transaction.
4015PSP_WAS_NOT_ASSIGNEDNo PSP was assigned to the transaction during routing.
4016EXTERNAL_MID_WAS_NOT_ASSIGNEDNo external MID was assigned to the transaction during routing.
4032EXPECTED_ROUTING_NO_MATCHThe transaction did not match any configured routing rule.

#Request Validation Declines

Request validation declines are raised when a required field is missing or cannot be resolved from the request. Fix the indicated field and resubmit with a new requestId.

CodeCode NameDescription
4001CREATED_DATE_MISSINGThe transaction's created date was missing.
4002EMAIL_MISSINGA required email value was missing from the request.
4005CARD_BRAND_MISSINGThe card brand could not be determined from the request.
4022DEVICE_IP_MISSINGThe device IP address was missing from the request.
4023EMAIL_FIELD_MISSINGThe email field was missing from the request.
4024PAYMENT_TX_DETAIL_MUST_PRESENT_FOR_REFUNDThe original payment details required for the refund were missing.
4025REDIRECTION_METADATA_MISSINGRedirection metadata required to continue the flow was missing.
4028APM_PAYLOAD_METADATA_IS_ABSENTThe apmPayload metadata required for this APM was missing.

#Special Codes

Reserved codes for specific business conditions.

CodeCode NameDescription
7777PAYMENT_WAS_DONE_BY_ANOTHER_MERCHANTThe payment referenced for a refund belongs to a different merchant.
19991MERCHANT_NOT_ENOUGH_FUNDSThe merchant has insufficient funds for the requested payout/refund.
20954REFUND_AMOUNT_MUST_BE_AT_MOST_PAYMENT_AMOUNTThe refund amount exceeds the original payment amount.

ℹ️ The above list covers the most commonly encountered decline codes on Exirom. For further inquiries or detailed cases regarding decline codes, please contact the Exirom support team.

See also: Error Handling Guide | APM Error Handling

Was this helpful?
PreviousSupported Currencies
NextGlossary