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:
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:
{
"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.