Error Handling

Standard error format

All error responses follow this format:

{
  "success": false,
  "error": {
    "message": "Human-readable error description",
    "code": 12001,
    "statusCode": 400,
    "traceId": "abc123def456..."
  }
}

Field	Description
`message`	Error description in English
`code`	Internal error code (see table below)
`statusCode`	HTTP response code
`traceId`	Unique identifier for technical support

Security note: Internal server errors (5xx) return a generic message ("An error has occurred...") to avoid exposing implementation details. The traceId lets the support team investigate the specific error.

Note on environments: Error codes, formats, and messages are identical in Live and Test environments. There are no differences in error handling between environments.

Error code catalog

Authentication and authorization errors (11xxx)

Code	HTTP	Description	Recommended action
11001	403	Invalid or missing API key	Verify the `X-API-KEY` header
11002	403	IP not allowed	Configure your IP in the dashboard (Integrations > API Keys)
11008	403	Access denied to the resource	Webcode mismatch, payment not created via External API, or environment error

Validation errors (12xxx)

Code	HTTP	Description	Recommended action
12001	400	Missing required parameter or invalid format	Review required fields and their formats
12002	400	Incorrect date format	Use ISO 8601 format (e.g. `2026-07-15T14:00:00Z`)
12006	400	Invalid country format	Use ISO 3166-1 alpha-2 (e.g. `ES`, `FR`, `DE`)
12009	400	Country not supported	Contact support for the list of available countries

Resource errors (10xxx)

Code	HTTP	Description	Recommended action
10404	404	Resource not found	Verify that `sessionId` or `paymentReference` is correct

POS errors (13xxx)

Code	HTTP	Description	Recommended action
13001	500	Payment provider error	Retry after a few seconds. If it persists, contact support
13004	502	Terminal communication error	Verify that the terminal is powered on and connected
13005	409	Terminal busy	Wait for the current transaction to finish and try again

Idempotency conflicts (409)

These conflicts do not carry an internal numeric code: the message distinguishes them from the POS busy 409 (13005).

Case	HTTP	Message (literal)	Recommended action
Same `Idempotency-Key`, different body	409	`Idempotency key reused with a different request body.`	Use a new key or resend the same body as the original request
Same `Idempotency-Key`, different endpoint	409	`Idempotency key already used for a different endpoint.`	Do not reuse the same key across different endpoints

Internal errors (99xxx)

Code	HTTP	Description	Recommended action
99001	500	Internal server error	Note the `traceId` and contact support

Example error response

{
  "success": false,
  "error": {
    "message": "External device is busy.",
    "code": 13005,
    "statusCode": 409,
    "traceId": "b2f3d36dc305249e8d1ebaa49ef616f1"
  }
}

Best practices

Retries

4xx errors: Do not retry (the problem is in the request)
5xx errors: Retry with exponential backoff (1s, 2s, 4s, 8s...)
409: if it is 13005 (terminal busy), wait 5-10 seconds and retry. If the message starts with Idempotency key…, do not retry blindly: fix the key or the request body
Always use Idempotency-Key so retries are safe (but make sure not to reuse it with a different body)

Logging

Log the traceId from error responses to simplify communication with technical support.

Pre-validation

Validate data before sending the request to avoid 400 errors:

amount.value must be a positive integer (cents)
amount.currency must be exactly 3 uppercase letters (EUR, GBP, or USD)
webcode cannot be empty
URLs (urlOk, urlKo) must be valid URLs with a protocol
reason on refunds must be one of the 5 exact allowed values

Developer documentation