Errors

Scan to Pay returns errors using standard HTTP status codes plus an extended set of 4xx codes in the 431–481 range for platform-specific failures. The error body, when present, contains a human-readable explanation of what went wrong.

This page is the canonical reference for every error code the API can return.

📘

For transaction outcomes, see Transaction states. Errors here are protocol-level failures (your request couldn't be processed). Once a transaction reaches the platform successfully, its outcome is communicated via TxState or NotificationStatus, not HTTP error codes.

Standard HTTP statuses

Scan to Pay extended error codes

Every Scan to Pay error returns one of the codes below in the 431–481 range. The HTTP status code identifies the error; the response body provides additional detail.

Code-related errors (431–456)

Merchant and transaction errors (460–481)

Platform errors (5xx range)

These are platform-side errors rather than client mistakes. They're worth distinguishing because the right response is "retry" rather than "fix your request."

Error response format

When the platform returns a 4xx or 5xx, the response body usually contains a JSON object with the error code and a message:

{
  "status": "FAILED",
  "errorCode": 432,
  "errorMessage": "Invalid Amount: amount must be greater than zero"
}

Older endpoints return a simpler shape:

{
  "error": "Validation error: merchantReference is required"
}

Always check the HTTP status code first, then the body for detail. The status code is the source of truth; the body is human help.

📘

Codes that return no errorMessage: 462 CNP_VALIDATION_STEP_UP_REQUIRED, 463 INVALID_TOKEN, 472 MERCHANT_WHITELIST_FAILURE, 479 CUSTOM_ERROR, and 480 PAYSHAP_ERROR return only the HTTP status and errorCode — there is no message string in the response body. Identify these by errorCode alone.

Handling errors in your integration

A simple decision tree for what to do with each class of error:

Best practices

• Always log the response body, not just the HTTP status. The body is where the specific reason lives.
• Map error codes to customer-facing copy in your UI. Never show CODE_LOCKED or CARD_HASH_FAILED to an end user. See ISO response codes for suggested customer messages.
• Distinguish retriable from non-retriable. 5xx and transient 4xx (516 INTERRUPTED) → retry. Validation 4xx → do not retry the same request.
• Capture request IDs if the response includes one — support tickets are much faster to resolve with a request ID attached.
• Use idempotent retries. When you retry, use the same merchantReference so the platform recognises it as the same logical attempt. See Idempotency.
• Don't catch and swallow. Especially on webhook handlers, surface errors prominently so on-call sees them.

What's next

• Map bank decline codes (464) to customer-facing copy → ISO response codes
• Understand transaction states vs HTTP errors → Transaction states
• Retry safely with the same reference → Idempotency
• Authentication failure modes → Authentication
• Webhook delivery failure modes → Webhooks