- Error Codes refer to the error code sent by the connector.
- Unified Error Codes refer to the generic error code sent by the Hyperswitch server, based on the connector’s error code. Hyperswitch groups the different error codes from connectors into more generic Unified Error Codes for structured relay of PSP errors, helping merchants derive patterns and determine the next steps for ongoing transactions.
| Error Code | Type | Description |
|---|---|---|
| IR | Invalid Request Error | Error caused due to invalid fields and values in API request |
| CE | Connector Error | Errors originating from connector’s end |
| HE | Hyperswitch Error | Errors originating from Hyperswitch’s end |
| WE | Webhook Error | Errors related to Webhooks |
| Error Codes | HTTP Status codes | Error Type | Error message | Error Handling |
|---|---|---|---|---|
| IR_00 | 501 | server_not_available | This API is under development and will be made available soon | No action required. If you require this feature, please reach out to Hyperswitch support |
| IR_01 | 401 | invalid_request_error | API key not provided or invalid API key used. Provide the API key in the Authorization header using api-key (e.g api-key: API_KEY) or create a new API key from the dashboard | Provide the API key in the Authorization header using api-key (e.g api-key: API_KEY) or create a new API key from the dashboard |
| IR_02 | 404 | invalid_request_error | Unrecognized request URL | Please recheck and enter the correct request URL. Refer to our API documentation |
| IR_03 | 405 | invalid_request_error | The HTTP method is not applicable for this API | Please recheck the HTTP method used in the request. Refer to our API documentation |
| IR_04 | 400 | invalid_request_error | Missing required param: “field_name” | Please pass the missing required parameter. Refer to our API documentation |
| IR_05 | 422 | invalid_request_error | “field_name” contains invalid data. Expected format is “expected_format” | Please pass the data in the expected format. Refer to our API documentation |
| IR_06 | 400 | invalid_request_error | “message” | Refer to our API documentation for required fields and format |
| IR_07 | 400 | invalid_request_error | Invalid value provided: “field_name” | Provide a valid value for the required fields in the expected format. Refer to our API documentation |
| IR_08 | 400 | invalid_request_error | Client secret was not provided | Provide the client secret received in payments/create API response |
| IR_09 | 400 | invalid_request_error | The client_secret provided does not match the client_secret associated with the Payment | Provide the same client secret received in payments/create API response for the corresponding payment |
| IR_10 | 400 | invalid_request_error | Customer has an existing mandate/subscription | Cancel the active mandates/subscriptions for the customer before proceeding to delete the customer data |
| IR_11 | 400 | invalid_request_error | Customer has already been redacted | Customer has already been redacted. No action required |
| IR_12 | 400 | invalid_request_error | Reached the maximum refund attempts | Maximum refund attempts reached for this payment. Please contact Hyperswitch support for attempting more refunds for the same payment |
| IR_13 | 400 | invalid_request_error | Refund amount exceeds the payment amount | Please verify and pass a refund amount equal to or less than the payment amount |
| IR_14 | 400 | invalid_request_error | This Payment could not be “current_flow” because it has a “field_name” of “current_value”. The expected state is “states” | Please verify the status of the payment and make sure that you are performing an action that is allowed for the current status of the payment |
| IR_15 | 400 | invalid_request_error | Invalid Ephemeral Key for the customer | Please pass the right Ephemeral key for the customer |
| IR_16 | 400 | invalid_request_error | “message” | Typically used when information involving multiple fields or previously provided information doesn’t satisfy a condition. Refer to our API documentation for required fields and format |
| IR_17 | 401 | invalid_request_error | Access forbidden, an invalid JWT token was used | Provide a valid JWT token to access the APIs |
| IR_18 | 401 | invalid_request_error | ”message” | The user is not authorised to update the customer, Contact Org. Admin for the appropriate access. |
| IR_19 | 400 | invalid_request_error | ”message” | Please check and retry with correct details. Refer to our API documentation |
| IR_20 | 400 | invalid_request_error | ”flow” not supported by the “connector” | Requested flow is not supported for this Connector. |
| IR_21 | 400 | invalid_request_error | Missing required params | Please add the required params in the request. Refer to our API documentation |
| IR_22 | 403 | invalid_request_error | Access forbidden. Not authorized to access this “resource” | Contact Org. Admin for the appropriate access. |
| IR_23 | 400 | invalid_request_error | ”message” | Use a supported file provider. Refer to our API documentation |
| IR_24 | 422 | processing_error | Invalid “wallet_name” wallet token | Share the correct wallet token. |
| IR_25 | 400 | invalid_request_error | Cannot delete the default payment method | Check if the Payment method is activated. Refer to Control centre to check this. |
| IR_26 | 400 | invalid_request_error | Invalid Cookie | Recheck the site setting for the cookies. |
| IR_27 | 404 | invalid_request_error | Extended card info does not exist | Recheck the card info shared in the request. |
| IR_28 | 400 | invalid_request_error | ”message” | Use a valid currency. Refer to our API documentation |
| IR_29 | 422 | invalid_request_error | ”message” | The data format is invalid for this request. Refer to our API documentation |
| IR_30 | 400 | invalid_request_error | Merchant connector account is configured with invalid config | Correct the config for merchant connector account |
| IR_31 | 400 | invalid_request_error | Card with the provided iin does not exist | Check the IIN (Issuer Identification Number) and ensure it is correct. |
| IR_32 | 400 | invalid_request_error | The provided card IIN length is invalid, please provide an iin with 6 or 8 digits | Provide a valid IIN with either 6 or 8 digits. |
| IR_33 | 400 | invalid_request_error | File not found / valid in the request | Ensure the required file is included in the request and is valid. Refer to our API documentation |
| IR_34 | 400 | invalid_request_error | Dispute id not found in the request | Ensure that a valid dispute ID is included in the request. |
| IR_35 | 400 | invalid_request_error | File purpose not found in the request or is invalid | Specify a valid file purpose in the request. |
| IR_36 | 400 | invalid_request_error | File content type not found / valid | Ensure the file content type is specified and is valid. |
| IR_37 | 404 | invalid_request_error | ”message” | Check the request for the resource being accessed and ensure it exists. |
| IR_38 | 400 | invalid_request_error | ”message” | Check for any duplicate entries in the request and correct them. |
| IR_39 | 400 | invalid_request_error | required payment method is not configured or configured incorrectly for all configured connectors | Verify that the required payment method is correctly configured for all connectors in use. |
| CE_00 | Status codes shared by the connectors | connector_error | “message” | The error code and message passed from the connectors. Refer to the respective connector’s documentation for more information on the error |
| CE_01 | 400 | processing_error | Payment failed during authorization with the connector. Retry payment | Retry the payment again as payment failed at the connector during authorization |
| CE_02 | 400 | processing_error | Payment failed during authentication with the connector. Retry payment | Retry the payment again as payment failed at the connector during authentication |
| CE_03 | 400 | processing_error | Capture attempt failed while processing with the connector | Capture failed for the payment at the connector. Please retry the payment |
| CE_04 | 400 | processing_error | The card data is invalid | Invalid card data passed. Please pass valid card data |
| CE_05 | 400 | processing_error | The card has expired | Card expired. Please pass valid card data |
| CE_06 | 400 | processing_error | Refund failed while processing with the connector. Retry refund | Refund failed to process at the connector. Please retry refund |
| CE_07 | 400 | processing_error | Verification failed while processing with the connector. Retry operation | Retry the operation again as verification failed at the connector |
| CE_08 | 400 | processing_error | Dispute operation failed while processing with connector. Retry operation | Retry the operation again as dispute failed at the connector |
| CE_09 | 400 | invalid_request_error | Payout validation failed | Retry the operation again with correct Payout details. |
| HE_00 | 422,500 | server_not_available | Resource not available right now, Please try again later. | Please Wait for a few moments and try again. If the error still persists, please reach out to Hyperswitch support |
| HE_01 | 400,422 | duplicate_request | Requested operation(Customer, Payments, Merchants, Refunds etc.) for these identifier already exists. | Please verify the Details(Customer, Payments, Merchants, Refunds, as applicable on the basis of request) and enter valid details. |
| HE_02 | 404 | object_not_found | Requested object(Customer, Payments, Merchants, Refunds etc.) does not exist in our records | Please verify the Details(Customer, Payments, Merchants, Refunds, as applicable on the basis of request) and enter valid details. |
| HE_03 | 500 | validation_error | Validation Failed for the requested operation with the given details. | Please verify the details again and enter valid details |
| HE_04 | 404 | object_not_found | Requested object(Customer, Payments, Merchants, Refunds etc.) does not exist in our records | Please verify the Details(Customer, Payments, Merchants, Refunds, as applicable on the basis of request) and enter valid details. |
| HE_05 | 500 | processing_error | Missing or invalid tenant details. | Please verify the tenant Details and try again. |
| WE_01 | 400 | invalid_request_error | Failed to authenticate the webhook | Please verify the authentication credentials and try again. |
| WE_02 | 400 | invalid_request_error | Bad request received in webhook | Check the request parameters and format, then try again. |
| WE_03 | 500 | router_error | There was some issue processing the webhook | Please try again later. If the issue persists, contact Hyperswitch support. |
| WE_04 | 404 | object_not_found | Webhook resource not found | Ensure the webhook URL is correct and the resource exists. |
| WE_05 | 400 | invalid_request_error | Unable to process the webhook body | Ensure the webhook body is correctly formatted and try again. |
| WE_06 | 400 | invalid_request_error | Merchant Secret set by merchant for webhook source verification is invalid | Verify the Merchant Secret, then try again. |
| Unified Error Code | Unified Error Categorisation | Unified Error message |
|---|---|---|
| UE_1000 | Customer Error | Issue with payment method details. |
| UE_2000 | Connector Declines | Issue with Configurations. |
| UE_3000 | Connector Error | Technical issue with PSP. |
| UE_4000 | Integration Error | Issue in the integration. |
| UE_9000 | Others | Something went wrong. |
Error Details Structure
Hyperswitch returns a structurederror_details object for failed payments.
This object combines error information from the connector (PSP), the issuer (bank), and Hyperswitch’s own interpretation.
Unified Details
This section is Hyperswitch’s understanding of the failure. It is created by looking at the issuer and connector error signals and mapping them to a standard meaning.
-
Category - The high-level unified error code (for example
UE_1000for payment method issues). - Message - High level unified error message that is consistent across different connectors.
-
Standardised Code - Code that identifies the specific cause for a failure within a broader error category such as
INVALID_EXPIRY_DATE. - Description - A detailed description of the error intended for debugging, analytics, and support teams.
- User Guidance Message - A user-friendly message that can be safely displayed to the customer. This message provides guidance on what the user should do to resolve the issue.
- Recommended Action - A field that tells merchants what action to take after a payment failure.
| Action | Description |
|---|---|
do_not_retry | Never retry with same card |
retry_later | Retry after some time |
retry_after_1_hour | Retry after 1 hour |
retry_after_24_hours | Retry after 24 hours |
retry_after_2_days | Retry after 2 days |
retry_after_4_days | Retry after 4 days |
retry_after_6_days | Retry after 6 days |
retry_after_8_days | Retry after 8 days |
retry_after_10_days | Retry after 10 days |
retry_after_instrument_update | Retry after updating payment details |
retry_with_different_payment_method_data | Use different payment method |
stop_recurring | Stop recurring payments |
Enhanced Errors
This table provides a standardized mapping that translates granular payment error into consistent standardised codes, customer-facing messages and description. The classification mappings, user guidance message and descriptions are subject to change at any time.| Standardised Code | Unified Code(Category) | Unified Message(Message) | User Guidance Message | Description |
|---|---|---|---|---|
| PAYMENT_METHOD_ISSUE | UE_1000 | Issue with payment method details | Issue with Payment Method details | Issue with Payment Method details |
| INVALID_CARD_NUMBER | UE_1000 | Issue with payment method details | The card number doesn’t look right. Please check it and try again | The card number is invalid |
| INVALID_EXPIRY_DATE | UE_1000 | Issue with payment method details | The card’s expiry date seems incorrect or has passed. Update it or use another card. | Expiry date is in the past or improperly formatted. |
| INVALID_CVV | UE_1000 | Issue with payment method details | The security code (CVV) is incorrect. Please re-enter it. | CVV is missing, malformed, or does not match issuer records |
| PM_ADDRESS_MISMATCH | UE_1000 | Issue with payment method details | The billing address doesn’t match what the bank has on file. Update it or use another card. | Address mismatch (AVS failed) |
| INSUFFICIENT_FUNDS | UE_1000 | Issue with payment method details | There aren’t enough funds on this card. Use another card or add funds and try again | The entered card has insufficient funds |
| CREDIT_LIMIT_EXCEEDED | UE_1000 | Issue with payment method details | This card has reached its credit limit. Use another card or contact your bank. | Transaction exceeds cardholder’s credit limit |
| VELOCITY_LIMIT_EXCEEDED | UE_1000 | Issue with payment method details | This card has hit a usage limit set by your bank. Try another card or contact your bank. | Transaction exceeds allowed frequency or velocity |
| CARD_LOST_OR_STOLEN | UE_1000 | Issue with payment method details | The bank has blocked this card. Please use a different card. | This card has been reported as lost or stolen |
| CARD_NOT_SUPPORTED_RESTRICTED | UE_1000 | Issue with payment method details | This card can’t be used for this payment. Try another card or payment method. | Card is restricted for this merchant, channel, or use case |
| ACCOUNT_CLOSED_OR_INVALID | UE_1000 | Issue with payment method details | This account is not active. Use a different payment method. | Account closed or invalid or missing |
| AUTHORIZATION_MISSING_OR_REVOKED | UE_1000 | Issue with payment method details | This payment can’t be completed because the prior authorization was canceled. Try another card or contact your bank. | Customer authorization is missing or was revoked |
| INCORRECT_AUTHENTICATION_CODE | UE_1000 | Issue with payment method details | The code you entered is incorrect. Request a new code and try again. | Incorrect authentication or verification code provided |
| PAYMENT_SESSION_TIMEOUT | UE_1000 | Issue with payment method details | Your session expired. Start the payment again. | Payment session expired before completion |
| AUTHENTICATION_FAILED | UE_1000 | Issue with payment method details | We couldn’t verify this payment with your bank. Try again or use a different payment method. | Authentication failed or was declined |
| PAYMENT_CANCELLED_BY_USER | UE_1000 | Issue with payment method details | The payment was canceled. If this wasn’t intended, please start a new payment. | Payment flow was canceled by user or system |
| TRANSACTION_NOT_PERMITTED | UE_1000 | Issue with payment method details | This payment method can’t be used for this type of purchase. Try another payment method. | This type of purchase is not permitted or supported |
| PM_TOKENISATION_ISSUE | UE_1000 | Issue with payment method details | We couldn’t save or use this card securely. Try again or use a different payment method. | Failed to tokenize or validate card credentials |
| CONFIGURATION_ISSUE | UE_2000 | Issue with configuration | Something went wrong. Try another Payment Method | Issue with Configurations |
| MERCHANT_INACTIVE | UE_2000 | Issue with configuration | Something went wrong. Try another Payment Method | Merchant configuration inactive or invalid |
| CFG_PM_NOT_ENABLED_OR_MISCONFIGURED | UE_2000 | Issue with configuration | Something went wrong. Try another Payment Method | Payment method not enabled for this merchant |
| CURRENCY_OR_CORRIDOR_NOT_ENABLED | UE_2000 | Issue with configuration | Something went wrong. Try another Payment Method | Currency or corridor not enabled |
| WALLET_OR_TOKEN_CONFIG_ISSUE | UE_2000 | Issue with configuration | Something went wrong. Try another Payment Method | Wallet or token configuration missing or incorrect |
| STORED_CREDENTIAL_OR_MIT_NOT_ENABLED | UE_2000 | Issue with configuration | Something went wrong. Try another Payment Method | Stored credential or MIT not enabled |
| THREEDS_CONFIGURATION_ISSUE | UE_2000 | Issue with configuration | Something went wrong. Try another Payment Method | 3DS not enabled or improperly integrated. |
| SUBSCRIPTION_PLAN_INACTIVE | UE_2000 | Issue with configuration | Something went wrong. Try another Payment Method | Attempted charge on inactive or expired subscription |
| DOWNSTREAM_TECHNICAL_ISSUE | UE_3000 | Technical Issue with PSP | Something went wrong. Try again or contact your bank | Downstream technical issue |
| ISSUER_UNAVAILABLE | UE_3000 | Technical Issue with PSP | Something went wrong. Try again or contact your bank | The card issuer’s bank is temporarily unavailable |
| TRANSACTION_TIMEDOUT | UE_3000 | Technical Issue with PSP | Something went wrong. Try again or contact your bank | Issuer timeout |
| DO_NOT_HONOR | UE_3000 | Technical Issue with PSP | Something went wrong. Try again or contact your bank | Do not honor |
| SUSPECTED_FRAUD | UE_3000 | Technical Issue with PSP | Something went wrong. Try again or contact your bank | Issuer flagged as suspected fraud. |
| PSP_FRAUD_ENGINE_DECLINE | UE_3000 | Technical Issue with PSP | Something went wrong. Try again or contact your bank | Declined by PSP fraud engine |
| COMPLIANCE_OR_SANCTIONS_RESTRICTION | UE_3000 | Technical Issue with PSP | Something went wrong. Try again or contact your bank | Sanctions or compliance blockage |
| PSP_ACQUIRER_ERROR | UE_3000 | Technical Issue with PSP | Something went wrong. Try again or contact your bank | Temporary acquirer internal error |
| THREEDS_AUTHENTICATION_SERVICE_ISSUE | UE_3000 | Technical Issue with PSP | Something went wrong. Try again or contact your bank | 3DS Authentication Service Failure |
| AUTHENTICATION_REQUIRED | UE_3000 | Technical Issue with PSP | Something went wrong. Try again or contact your bank | Authentication is required |
| INTEGRATION_ISSUE | UE_4000 | Issue with integration | Something went wrong. Try another payment method or contact your bank | Issue with Integration |
| MISSING_OR_INVALID_PARAM | UE_4000 | Issue with integration | Something went wrong. Try another payment method or contact your bank | Missing or invalid parameter |
| INVALID_CREDENTIALS | UE_4000 | Issue with integration | Something went wrong. Try another payment method or contact your bank | Invalid credentials |
| OPERATION_NOT_ALLOWED | UE_4000 | Issue with integration | Something went wrong. Try another payment method or contact your bank | Operation not allowed |
| DUPLICATE_REQUEST | UE_4000 | Issue with integration | Something went wrong. Try another payment method or contact your bank | Duplicate or Idempotent request |
| INVALID_STATE | UE_4000 | Issue with integration | Something went wrong. Try another payment method or contact your bank | Invalid state of operation |
| THREEDS_DATA_OR_PROTOCOL_INVALID | UE_4000 | Issue with integration | Something went wrong. Try another payment method or contact your bank | 3DS payload invalid or inconsistent |
| RATE_LIMIT | UE_4000 | Issue with integration | Something went wrong. Try another payment method or contact your bank | API rate limit exceeded |
| INTEG_CRYPTOGRAPHIC_ISSUE | UE_4000 | Issue with integration | Something went wrong. Try another payment method or contact your bank | Token or cryptographic integration issue |
| GEN_UNKNOWN_ERROR | UE_9000 | Something went wrong | Something went wrong | Something went wrong |