Skip to content

Error codes

Errors returned by the Cardencer checkout SDK and API, what they mean and how to fix them.

Every error tells you what happened and what to do next. Show customer-facing messages for card errors, and log everything else with the payment_id.

SDK errors#

confirmPayment() and other SDK calls resolve with an error object when something goes wrong:

js
const { error } = await hyper.confirmPayment({ widgets, confirmParams: { return_url }, redirect: "if_required" });
if (error) console.log(error.type, error.message);
error.type Message Fix
invalid_request_error Invalid api key Initialise the SDK with a valid publishable key (pk_snd_… or pk_prd_…) matching the environment.
invalid_request_error Invalid value for <parameter> Check the option you passed to the SDK.
invalid_request_error Missing required parameter: <parameter> Pass the missing option.
invalid_request_error Invalid client secret Use the client_secret of a payment created with the same account and environment, and create a new payment if it expired.
invalid_request_error Invalid promise Pass the promise returned by your SDK loader.
card_error, validation_error Card declined or invalid card details Show error.message and let the customer try again or use another card.
processing_error Payment failed with the payment processor Ask the customer to retry or use another card.
internal_server_error Server is unavailable Retry after a few seconds.
object_not_found Payment does not exist Check the client_secret; the payment may belong to another environment.
confirm_payment_failed An unknown error occurred Retrieve the payment from your server to see its status, then retry.

API errors#

API errors return an HTTP status and a JSON body:

json
{
  "error": {
    "type": "invalid_request",
    "message": "Missing required param: amount",
    "code": "IR_04"
  }
}

Codes are grouped by prefix:

Prefix Meaning
IR Invalid request: fix the request and retry.
CE Processing error from the acquirer or card network.
HE Cardencer platform error.
WE Webhook error.

Common codes#

Code HTTP Message Fix
IR_00 501 This API is under development The endpoint is not available on your account.
IR_01 401 API key not provided or invalid API key used Send the full secret key in the api-key header, matching the environment.
IR_02 404 Unrecognized request URL Check the path and base URL.
IR_03 405 The HTTP method is not applicable for this API Check the method in the API reference.
IR_04 400 Missing required param: field_name Add the field.
IR_05 422 field_name contains invalid data Send the expected format.
IR_06 400 (message) Read the message; a field combination is invalid.
IR_07 400 Invalid value provided: field_name Send an allowed value.
IR_08 400 Client secret was not provided Pass the client_secret.
IR_09 400 The client_secret provided does not match Use the secret of this payment.
IR_16 400 (message): a condition on several fields, or on the object's current state, is not met Retrieve the payment and check its status before you confirm, capture or cancel.
IR_28 400 (message) Use a supported currency.
CE_01 400 Payment failed during authorization Ask the customer to retry or use another card.
CE_02 400 Payment failed during authentication 3D Secure failed; retry or use another card.
CE_03 400 Capture attempt failed Retry the capture.
CE_04 400 The card data is invalid Ask for correct card details.
CE_05 400 The card has expired Ask for another card.
CE_06 400 Refund failed Retry the refund.
HE_00 422/500 Resource not available right now Retry after a few seconds; contact support if it persists.
HE_01 400/422 Requested operation for these identifier already exists You reused an ID (payment, refund, customer). Use a new one or retrieve the existing object.
HE_02 404 Requested object does not exist Check the ID and the environment.
HE_03 500 Validation failed Check the details and retry.
WE_01 400 Failed to authenticate the webhook Check your webhook signing key.

Declines#

When the acquirer or issuer declines a card, the payment ends failed and carries more detail:

Field Content
error_code, error_message The processor's decline code and message.
unified_code, unified_message A normalised category you can map to customer messages.
issuer_error_code, issuer_error_message The issuing bank's response, when available.

Show the customer a short message ("Your card was declined. Please try another card.") and keep the codes in your logs.

Rate limits#

HTTP 429 means you sent too many requests, or another request is updating the same object. Retry with exponential backoff. See Authentication.