---
title: Error Codes
---

Hyperswitch uses Error codes, types, and messages to communicate errors during API calls. There are three types of error codes:

| 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.                                                              |