Error Handling

All error responses follow a consistent structure:

{
  "errorModel": {
    "errorCode": "ERROR_CODE",
    "message": "Human-readable description",
    "descriptors": ["additional", "context"]
  }
}

Error Codes

Authentication & Authorization

Error Code	Description
AUTHORIZATION	The API key (External Device) does not exist or has been disabled.
EXTERNAL_DEVICE_HAS_NO_RIGHT_AUTHORITY	The API key does not have permission for this operation. For example, a key with COUPON permissions cannot process payments.

Transaction Key Errors

Error Code	Description
X_TRANSACTION_KEY_FORMAT_IS_NOT_VALID	The Transaction Key does not match the required format: ^[0-9a-fA-F]{32}$
X_TRANSACTION_HAS_NO_RIGHT_AUTHORITY	The Transaction Key does not have permission for this operation.
X_TRANSACTION_HAS_EXPIRED	The Transaction Key has expired and is no longer valid. The user must generate a new QR code.
X_TRANSACTION_IS_NOT_IN_ACTIVE_STATUS	The Transaction Key has already been used or manually invalidated.

Payment Errors

Error Code	Description
INSUFFICIENT_CREDIT	The user does not have enough credits. Only occurs with paymentType: "CREDIT". Retry with "EXTERNAL_PAYMENT" if the POS does not support split payments.
CREDIT_TRANSACTION_PREVIEW_HAS_EXPIRED	Too much time has passed since the preview was created. Create a new preview.
CREDIT_TRANSACTION_HAS_ALREADY_BEEN_FINALIZED_WITH_DIFFERENT_ITEMS	The finalize endpoint was already called for this transaction ID with different items.

Idempotency Errors

Error Code	Description
IDEMPOTENCY_KEY_HAS_ALREADY_BEEN_USED_WITH_DIFFERENT_VALUES	This idempotency key was used in a previous request with different payload. Use a new unique key.

Validation Errors

Error Code	Description
COULD_NOT_MAP_BIG_DECIMAL_TO_VAT_ENUM_VALUE	Unsupported VAT rate. Supported values: 0, 1, 2, 3, 4, 5, 5.5, 6, 7, 7.7, 8, 9, 9.5, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27

Refund Errors

Error Code	Description
CREDIT_TRANSACTION_CAN_NO_LONGER_BE_REFUNDED_BY_EXTERNAL_DEVICE	The 24-hour refund window has passed.

Recommended Handling

INSUFFICIENT_CREDIT Flow

If your POS does not support split payments:

Expired Preview

If CREDIT_TRANSACTION_PREVIEW_HAS_EXPIRED is returned on finalize, the preview timed out. Start the flow over by creating a new preview. The user may need to generate a new QR code if their Transaction Key also expired.

Expired Preview

If CREDIT_TRANSACTION_PREVIEW_HAS_EXPIRED is returned on finalize, the preview timed out. Start the flow over by creating a new preview. The user may need to generate a new QR code if their Transaction Key also expired.

Failed External Payment

If the cash/card payment after preview fails:

Never finalize a transaction if the external payment portion was not collected.