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

| 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                                                                                                                        | Please provide a valid JWT token to access the APIs                                                                                                                                  |
| 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                                                                                                                    |
| HE_00       | 500                                   | server_not_available  | Something went wrong                                                                                                                                                | Please retry the operation. If the error still persists, please reach out to Hyperswitch support                                                                                         |
| HE_01       | 400                                   | duplicate_request     | Duplicate refund request. Refund already attempted with the refund ID                                                                                               | Please verify the refund id and no action required if the refund is already attempted                                                                                                |
| HE_01       | 400                                   | duplicate_request     | Duplicate mandate request. Mandate already attempted with the Mandate ID                                                                                            | Please verify the mandate id and no action required if the mandate is already created                                                                                                |
| HE_01       | 400                                   | duplicate_request     | The merchant account with the specified details already exists in our records                                                                                       | Please verify the merchant account details and no action required if the merchant account is already created                                                                         |
| HE_01       | 400                                   | duplicate_request     | The merchant connector account with the specified details already exists in our records                                                                             | Please verify the merchant connector account details and no action required if the merchant connector account is already created                                                     |
| HE_01       | 400                                   | duplicate_request     | The payment method with the specified details already exists in our records                                                                                         | Please verify the mandate id and no action required if the mandate is already created                                                                                                |
| HE_02       | 400                                   | object_not_found      | Refund does not exist in our records                                                                                                                                | Please verify the refund details and enter valid details                                                                                                                             |
| HE_02       | 400                                   | object_not_found      | Customer does not exist in our records                                                                                                                              | Please verify the customer details and enter valid details                                                                                                                           |
| HE_02       | 400                                   | object_not_found      | Payment does not exist in our records                                                                                                                               | Please verify the payment details and enter valid details                                                                                                                            |
| HE_02       | 400                                   | object_not_found      | Payment method does not exist in our records                                                                                                                        | Please verify the payment method details and enter valid details                                                                                                                     |
| HE_02       | 400                                   | object_not_found      | Merchant account does not exist in our records                                                                                                                      | Please verify the merchant account details and enter valid details                                                                                                                   |
| HE_02       | 400                                   | object_not_found      | Merchant connector account does not exist in our records                                                                                                            | Please verify the merchant connector details and enter valid details                                                                                                                 |
| HE_02       | 400                                   | object_not_found      | Resource ID does not exist in our records                                                                                                                           | Please verify the resource ID and enter valid details                                                                                                                                |
| HE_02       | 400                                   | object_not_found      | Mandate does not exist in our records                                                                                                                               | Please verify the mandate details and enter valid details                                                                                                                            |
| HE_03       | 400                                   | validation_error      | Refunds not possible through Hyperswitch. Please raise Refunds through the “connector” dashboard                                                                        | Please raise refunds request from the respective connector’s dashboard as the connectors don’t provide a Refunds API for Hyperswitch to process                                      |
| HE_03       | 400                                   | validation_error      | Mandate Validation Failed                                                                                                                                           | Please verify the mandate details again and enter valid details                                                                                                                      |
| HE_04       | 400                                   | validation_error      | The payment has not succeeded yet. Please pass a successful payment to initiate refund                                                                              | Please verify the request parameters and retry the payment. If the error still persists, please reach out to Hyperswitch support                                                     |
| HE_04       | 400                                   | object_not_found      | Successful payment not found for the given payment id                                                                                                               | Please verify the payment details and status as you can attempt refunds only for payments with success status                                                                        |
| HE_04       | 400                                   | object_not_found      | The connector provided in the request is incorrect or not available                                                                                                 | Please verify your connector configuration and provide a valid connector that is enabled for your account                                                                            |
| HE_04       | 400                                   | object_not_found      | Address does not exist in our records                                                                                                                               | Please verify the address details and pass valid address details                                                                                                                     |
