Essentials
Error Codes
Essentials
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 | 503 | validation_error | Return URL is not configured and not passed in payments request | Please configure the return URL through the dashboard or by updating your merchant account details. Alternatively, you can pass the return URL during every payment request’s body |
| 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 |