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

Error CodeTypeDescription
IRInvalid Request ErrorError caused due to invalid fields and values in API request
CEConnector ErrorErrors originating from connector’s end
HEHyperswitch ErrorErrors originating from Hyperswitch’s end
Error CodesHTTP Status codesError TypeError messageError Handling
IR_00501server_not_availableThis API is under development and will be made available soonNo action required. If you require this feature, please reach out to Hyperswitch support
IR_01401invalid_request_errorAPI 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 dashboardProvide 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_02404invalid_request_errorUnrecognized request URLPlease recheck and enter the correct request URL. Refer to our API documentation
IR_03405invalid_request_errorThe HTTP method is not applicable for this APIPlease recheck the HTTP method used in the request. Refer to our API documentation
IR_04400invalid_request_errorMissing required param: “field_name”Please pass the missing required parameter. Refer to our API documentation
IR_05422invalid_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_06400invalid_request_error“message”Refer to our API documentation for required fields and format
IR_07400invalid_request_errorInvalid value provided: “field_name”Provide a valid value for the required fields in the expected format. Refer to our API documentation
IR_08400invalid_request_errorClient secret was not providedProvide the client secret received in payments/create API response
IR_09400invalid_request_errorThe client_secret provided does not match the client_secret associated with the PaymentProvide the same client secret received in payments/create API response for the corresponding payment
IR_10400invalid_request_errorCustomer has an existing mandate/subscriptionCancel the active mandates/subscriptions for the customer before proceeding to delete the customer data
IR_11400invalid_request_errorCustomer has already been redactedCustomer has already been redacted. No action required
IR_12400invalid_request_errorReached the maximum refund attemptsMaximum refund attempts reached for this payment. Please contact Hyperswitch support for attempting more refunds for the same payment
IR_13400invalid_request_errorRefund amount exceeds the payment amountPlease verify and pass a refund amount equal to or less than the payment amount
IR_14400invalid_request_errorThis 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_15400invalid_request_errorInvalid Ephemeral Key for the customerPlease pass the right Ephemeral key for the customer
IR_16400invalid_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_17401invalid_request_errorAccess forbidden, an invalid JWT token was usedPlease provide a valid JWT token to access the APIs
CE_00Status codes shared by the connectorsconnector_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_01400processing_errorPayment failed during authorization with the connector. Retry paymentRetry the payment again as payment failed at the connector during authorization
CE_02400processing_errorPayment failed during authentication with the connector. Retry paymentRetry the payment again as payment failed at the connector during authentication
CE_03400processing_errorCapture attempt failed while processing with the connectorCapture failed for the payment at the connector. Please retry the payment
CE_04400processing_errorThe card data is invalidInvalid card data passed. Please pass valid card data
CE_05400processing_errorThe card has expiredCard expired. Please pass valid card data
CE_06400processing_errorRefund failed while processing with the connector. Retry refundRefund failed to process at the connector. Please retry refund
CE_07400processing_errorVerification failed while processing with the connector. Retry operationRetry the operation again as verification failed at the connector
HE_00500server_not_availableSomething went wrongPlease retry the operation. If the error still persists, please reach out to Hyperswitch support
HE_01400duplicate_requestDuplicate refund request. Refund already attempted with the refund IDPlease verify the refund id and no action required if the refund is already attempted
HE_01400duplicate_requestDuplicate mandate request. Mandate already attempted with the Mandate IDPlease verify the mandate id and no action required if the mandate is already created
HE_01400duplicate_requestThe merchant account with the specified details already exists in our recordsPlease verify the merchant account details and no action required if the merchant account is already created
HE_01400duplicate_requestThe merchant connector account with the specified details already exists in our recordsPlease verify the merchant connector account details and no action required if the merchant connector account is already created
HE_01400duplicate_requestThe payment method with the specified details already exists in our recordsPlease verify the mandate id and no action required if the mandate is already created
HE_02400object_not_foundRefund does not exist in our recordsPlease verify the refund details and enter valid details
HE_02400object_not_foundCustomer does not exist in our recordsPlease verify the customer details and enter valid details
HE_02400object_not_foundPayment does not exist in our recordsPlease verify the payment details and enter valid details
HE_02400object_not_foundPayment method does not exist in our recordsPlease verify the payment method details and enter valid details
HE_02400object_not_foundMerchant account does not exist in our recordsPlease verify the merchant account details and enter valid details
HE_02400object_not_foundMerchant connector account does not exist in our recordsPlease verify the merchant connector details and enter valid details
HE_02400object_not_foundResource ID does not exist in our recordsPlease verify the resource ID and enter valid details
HE_02400object_not_foundMandate does not exist in our recordsPlease verify the mandate details and enter valid details
HE_03400validation_errorRefunds not possible through Hyperswitch. Please raise Refunds through the “connector” dashboardPlease raise refunds request from the respective connector’s dashboard as the connectors don’t provide a Refunds API for Hyperswitch to process
HE_03400validation_errorMandate Validation FailedPlease verify the mandate details again and enter valid details
HE_04400validation_errorThe payment has not succeeded yet. Please pass a successful payment to initiate refundPlease verify the request parameters and retry the payment. If the error still persists, please reach out to Hyperswitch support
HE_04400object_not_foundSuccessful payment not found for the given payment idPlease verify the payment details and status as you can attempt refunds only for payments with success status
HE_04400object_not_foundThe connector provided in the request is incorrect or not availablePlease verify your connector configuration and provide a valid connector that is enabled for your account
HE_04400object_not_foundAddress does not exist in our recordsPlease verify the address details and pass valid address details