API errors

The lite API returns structured errors that help you understand what failed, fix the request, and retry safely when the outcome is uncertain. Use the first sections to understand the error model. Use Errors by API to see the exact responses returned by each operation. Payment states such as AUTHORIZED, CAPTURED, VOIDED, and REFUNDED describe the payment lifecycle and are documented separately.

Read an error

Standard API errors return an errors array and a request_id.

{
  "errors": [
    {
      "category": "CONNECTION",
      "code": "PROVIDER_CONNECTION_ERROR",
      "message": "A connection error occurred with the payment provider. Retry after a short delay.",
      "retriable": true
    }
  ],
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

A validation response can contain one item for each field that failed validation.

Field	Type	Presence	Description
`errors`	array	Always	One or more errors returned for the request.
`errors[].category`	string	Always	The broad source of the error.
`errors[].code`	string	Always	The machine-readable code your integration should handle.
`errors[].message`	string	Always	A human-readable explanation. Do not use it for program logic.
`errors[].retriable`	boolean	Always	Whether retrying may succeed without correcting the underlying request data.
`errors[].field`	string	Conditional	The request field that failed validation.
`request_id`	string	Always	The request identifier. Include it when contacting lite support.

Fields such as retry_after_seconds, documentation_url, routing_attempts, error_id, business_id, and entity_id are not currently returned.

Validation errors

Field-level validation returns MISSING_REQUIRED_FIELD or INVALID_FIELD_VALUE. The field value identifies the property that failed.

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "MISSING_REQUIRED_FIELD",
      "message": "amount should not be empty",
      "field": "amount",
      "retriable": false
    },
    {
      "category": "VALIDATION",
      "code": "INVALID_FIELD_VALUE",
      "message": "currency must be a supported value",
      "field": "currency",
      "retriable": false
    }
  ],
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Fix all fields listed in the response before resubmitting the request.

HTTP status codes

The HTTP status identifies the general class of failure. Use the error code for application logic.

Status	Summary	Meaning
400	Bad Request	The request is malformed, incomplete, or invalid.
401	Unauthorized	Authentication or merchant context is missing or invalid.
403	Forbidden	The caller does not have permission to perform the operation or access the resource.
404	Not Found	The requested payment, instrument, token, or other entity was not found.
409	Conflict	The request conflicts with an existing request or the resource’s current state.
422	Unprocessable Entity	The request was understood, but the payment instrument, issuer, authentication, or risk outcome prevented completion.
500	Internal Server Error	An unexpected error occurred inside lite.
502	Bad Gateway	lite could not communicate successfully with an upstream provider.
503	Service Unavailable	A provider or payment workflow is temporarily unavailable.
504	Gateway Timeout	A provider did not respond before the timeout.

Error categories

Every error belongs to a category. Use it as a fallback when your integration receives a code it does not recognize.

Category	Meaning	First action
`SETUP`	Authentication, permissions, merchant context, or access control.	Check credentials, context, permissions, and resource ownership.
`VALIDATION`	Invalid request data, duplicate requests, or missing resources.	Correct the request or verify the referenced identifier.
`INSTRUMENT`	The payment token or instrument is missing, expired, or invalid.	Obtain or create a valid payment instrument.
`ISSUER`	The issuer declined the transaction.	Ask the customer to use another card or payment method.
`FRAUD`	Risk controls or 3D Secure authentication prevented the operation.	Follow the code-specific action and avoid blind retries.
`WORKFLOW`	The operation is not allowed in the resource’s current state.	Retrieve the current status before deciding the next operation.
`CONNECTION`	A provider or payment workflow could not be reached or completed.	Check the payment status, then retry safely when allowed.
`SYSTEM`	An unexpected failure occurred inside lite.	Check the payment status and retry with backoff when safe.

Error codes

The table below lists the error codes currently returned by the payment, payment-link, instrument, device-payment, POS, and 3D Secure services.

Code	HTTP	Category	Retriable	Meaning	How to handle
`UNAUTHORIZED`	401	`SETUP`	No	Authentication, merchant context, or terminal context is missing or invalid.	Send valid credentials and the required merchant or terminal context.
`FORBIDDEN`	403	`SETUP`	No	The caller does not have permission to perform the operation.	Check the account permissions and product enablement.
`ENTITY_ACCESS_DENIED`	403	`SETUP`	No	The requested resource is not accessible to the current merchant.	Verify that the resource belongs to the authenticated merchant.
`INVALID_REQUEST`	400	`VALIDATION`	No	The request is malformed or fails a request-level business validation.	Correct the request using the endpoint documentation and resubmit it.
`MISSING_REQUIRED_FIELD`	400	`VALIDATION`	No	A required field is missing.	Add the field identified by `field`, then resubmit the request.
`INVALID_FIELD_VALUE`	400	`VALIDATION`	No	A field has an invalid value or format.	Correct the field identified by `field`, then resubmit the request.
`INVALID_AMOUNT`	400	`VALIDATION`	No	The order total does not match the authorize amount.	Correct the amount or order totals before resubmitting.
`TOKEN_NOT_FOUND`	404	`VALIDATION`	No	The referenced payment token was not found.	Verify the token ID or tokenize the payment method again.
`DUPLICATE_ENTITY`	409	`VALIDATION`	No	An entity with the same details already exists.	Retrieve and use the existing entity instead of creating another one.
`DUPLICATE_REQUEST`	409	`VALIDATION`	No	A conflicting request or resource already exists.	Reuse the original result when appropriate, or send a new unique reference.
`PAYMENT_NOT_FOUND`	404	`VALIDATION`	No	The requested payment was not found.	Verify the payment ID and merchant context.
`ENTITY_NOT_FOUND`	404	`VALIDATION`	No	The requested entity was not found.	Verify the entity ID and merchant context.
`EXPIRED_TOKEN`	422	`INSTRUMENT`	No	The payment token has expired.	Tokenize the card again and submit a new payment attempt.
`INVALID_TOKEN`	422	`INSTRUMENT`	No	The payment token is invalid or is not active.	Obtain a valid active token before retrying.
`DECLINED`	422	`ISSUER`	No	The issuer declined the transaction.	Ask the customer to use a different card or payment method.
`FRAUD_DETECTED`	422	`FRAUD`	No	The transaction was declined for security reasons.	Do not retry the same transaction. Follow your risk-review process where applicable.
`RISK_DECLINED`	422	`FRAUD`	No	lite risk controls declined the transaction.	Review the transaction in the dashboard. Do not retry blindly.
`AUTHENTICATION_FAILED`	422	`FRAUD`	No	3D Secure authentication failed.	Ask the customer to try again or use a different card.
`AUTHENTICATION_UNAVAILABLE`	422	`FRAUD`	Yes	The authentication service is temporarily unavailable.	Retry after a short delay. Create a new customer attempt only when required by your flow.
`INVALID_STATE`	409	`WORKFLOW`	No	The operation is not allowed in the resource’s current state.	Retrieve the current status and perform an operation valid for that state.
`PROVIDER_TIMEOUT`	504	`CONNECTION`	Yes	An upstream service timed out.	Check the payment status first, then retry with backoff if the operation was not completed.
`PROVIDER_CONNECTION_ERROR`	502	`CONNECTION`	Yes	lite could not communicate successfully with an upstream provider.	Check the payment status first, then retry after a short delay.
`WORKFLOW_SUBMISSION_FAILED`	503	`CONNECTION`	Yes	The payment workflow is temporarily unavailable or could not accept the operation.	Check the payment status, then retry with backoff.
`PROVIDER_UNAVAILABLE`	503	`CONNECTION`	Yes	The payment provider is temporarily unavailable.	Retry with backoff or use an available fallback payment method.
`GATEWAY_TIMEOUT`	504	`CONNECTION`	Yes	The payment provider timed out.	Check the payment status first, then retry after a short delay.
`INTERNAL_ERROR`	500	`SYSTEM`	Yes	An unexpected error occurred inside lite.	Check the payment status before retrying. Retry with backoff and contact support if the error persists.

Retry failed requests

Branch on code. For an unknown code, use category to identify the type of problem and retriable to determine whether a retry may succeed. Never branch on message. A retriable: true response permits a controlled retry. It does not confirm that the original payment operation failed. For payment operations, retrieve the payment status before retrying or creating another payment attempt. This prevents duplicate authorizations, captures, voids, or refunds. Use exponential backoff and cap the number of attempts. Stop retrying when the operation reaches a final state or when the retry limit is reached. A retriable: false response requires a change before another attempt, such as correcting the request, using another payment instrument, or waiting for a valid workflow state. Log the request_id for every failed request and include it when contacting lite support.

Errors by API

Find the errors each lite API can return. Open an example to see the exact response body. Values such as <request-id> and <status> are generated at runtime.

Common errors

These responses are shared by several APIs. Each endpoint section identifies the shared responses that apply.

Merchant context is missing

Returned by: Payment APIs under /api/v1/payments/*HTTP 401 Unauthorized · UNAUTHORIZED · Retriable: No

{
  "errors": [
    {
      "category": "SETUP",
      "code": "UNAUTHORIZED",
      "message": "Merchant context is required",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

Authentication, merchant, or terminal context is missing

Returned by: Instruments, POS, Payment Links, device payments, and some 3D Secure browser flowsHTTP 401 Unauthorized · UNAUTHORIZED · Retriable: No

{
  "errors": [
    {
      "category": "SETUP",
      "code": "UNAUTHORIZED",
      "message": "Authentication is required to access this resource.",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

The request uses camelCase or contains unknown keys where snake_case is expected

Returned by: Payment and instrument APIsHTTP 400 Bad Request · INVALID_REQUEST · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "INVALID_REQUEST",
      "message": "The request is malformed. Fix the JSON structure and resubmit.",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

A required request field is missing

Returned by: Endpoints with request validationHTTP 400 Bad Request · MISSING_REQUIRED_FIELD · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "MISSING_REQUIRED_FIELD",
      "message": "<field> should not be empty",
      "field": "<field>",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

A request field fails validation

Returned by: Endpoints with request validationHTTP 400 Bad Request · INVALID_FIELD_VALUE · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "INVALID_FIELD_VALUE",
      "message": "<validation message>",
      "field": "<field>",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

An unhandled failure occurs

Returned by: Payment and instrument APIsHTTP 500 Internal Server Error · INTERNAL_ERROR · Retriable: Yes

{
  "errors": [
    {
      "category": "SYSTEM",
      "code": "INTERNAL_ERROR",
      "message": "An unexpected error occurred. Retry with backoff. lite.sa has been alerted.",
      "retriable": true
    }
  ],
  "request_id": "<request-id>"
}

Payments

Authorize a payment

POST /api/v1/payments Also returned: missing merchant context, malformed request, field validation, and internal errors.

The line items, VAT, and shipping total do not match the authorization amount

HTTP 400 Bad Request · INVALID_AMOUNT · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "INVALID_AMOUNT",
      "message": "Order total price does not match authorize amount",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

The instrument ID is empty or is not a valid UUID

HTTP 400 Bad Request · INVALID_REQUEST · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "INVALID_REQUEST",
      "message": "Payment instrument id is invalid or malformed",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

The merchant ID is missing from the payment input

HTTP 400 Bad Request · INVALID_REQUEST · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "INVALID_REQUEST",
      "message": "Merchant ID is required",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

The amount or currency is invalid

HTTP 400 Bad Request · INVALID_REQUEST · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "INVALID_REQUEST",
      "message": "Invalid payment amount or currency",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

The terminal ID is missing for a merchant-initiated POS payment

HTTP 400 Bad Request · INVALID_REQUEST · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "INVALID_REQUEST",
      "message": "Terminal ID is required for merchant-initiated payments",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

The payment token does not exist or was deleted

HTTP 404 Not Found · TOKEN_NOT_FOUND · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "TOKEN_NOT_FOUND",
      "message": "The token was not found. Verify the token ID or re-tokenize.",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

The payment token has expired

HTTP 422 Unprocessable Entity · EXPIRED_TOKEN · Retriable: No

{
  "errors": [
    {
      "category": "INSTRUMENT",
      "code": "EXPIRED_TOKEN",
      "message": "The payment token has expired. Re-tokenize the card.",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

The payment token is not active

HTTP 422 Unprocessable Entity · INVALID_TOKEN · Retriable: No

{
  "errors": [
    {
      "category": "INSTRUMENT",
      "code": "INVALID_TOKEN",
      "message": "The payment token is invalid. Re-tokenize the card.",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

lite cannot resolve the payment instrument

HTTP 422 Unprocessable Entity · INVALID_TOKEN · Retriable: No

{
  "errors": [
    {
      "category": "INSTRUMENT",
      "code": "INVALID_TOKEN",
      "message": "Invalid payment instrument",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

A payment instrument with the same details already exists

HTTP 409 Conflict · DUPLICATE_ENTITY · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "DUPLICATE_ENTITY",
      "message": "Entity with same details pre-exists. List the instances of the entity to find or edit the existing one.",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

A request with the same order reference is already being processed

HTTP 409 Conflict · DUPLICATE_REQUEST · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "DUPLICATE_REQUEST",
      "message": "A request with this idempotency key already exists. Use the original response or a new key.",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

The payment instrument lookup times out

HTTP 504 Gateway Timeout · PROVIDER_TIMEOUT · Retriable: Yes

{
  "errors": [
    {
      "category": "CONNECTION",
      "code": "PROVIDER_TIMEOUT",
      "message": "The provider response timed out. Retry — check payment status first to avoid duplicates.",
      "retriable": true
    }
  ],
  "request_id": "<request-id>"
}

The payment instrument lookup fails because of a connection error

HTTP 502 Bad Gateway · PROVIDER_CONNECTION_ERROR · Retriable: Yes

{
  "errors": [
    {
      "category": "CONNECTION",
      "code": "PROVIDER_CONNECTION_ERROR",
      "message": "A connection error occurred with the payment provider. Retry after a short delay.",
      "retriable": true
    }
  ],
  "request_id": "<request-id>"
}

lite cannot start the payment operation

HTTP 503 Service Unavailable · WORKFLOW_SUBMISSION_FAILED · Retriable: Yes

{
  "errors": [
    {
      "category": "CONNECTION",
      "code": "WORKFLOW_SUBMISSION_FAILED",
      "message": "Payment orchestrator is temporarily unavailable",
      "retriable": true
    }
  ],
  "request_id": "<request-id>"
}

The original idempotent request is still processing when the wait period ends

HTTP 500 Internal Server Error · INTERNAL_ERROR · Retriable: Yes

{
  "errors": [
    {
      "category": "SYSTEM",
      "code": "INTERNAL_ERROR",
      "message": "An unexpected error occurred. Retry with backoff. lite.sa has been alerted.",
      "retriable": true
    }
  ],
  "request_id": "<request-id>"
}

An unexpected error occurs while resolving the payment instrument

HTTP 500 Internal Server Error · INTERNAL_ERROR · Retriable: Yes

{
  "errors": [
    {
      "category": "SYSTEM",
      "code": "INTERNAL_ERROR",
      "message": "An unexpected error occurred. Retry with backoff. lite.sa has been alerted.",
      "retriable": true
    }
  ],
  "request_id": "<request-id>"
}

If an earlier request with the same idempotency key already failed, lite replays the original HTTP status and error body.

Capture a payment

POST /api/v1/payments/:paymentId/capture Also returned: missing merchant context, malformed request, field validation, and internal errors.

`paymentId` is missing

HTTP 400 Bad Request · MISSING_REQUIRED_FIELD · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "MISSING_REQUIRED_FIELD",
      "message": "Payment ID is required",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

The payment is not found for the merchant

HTTP 404 Not Found · PAYMENT_NOT_FOUND · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "PAYMENT_NOT_FOUND",
      "message": "Payment not found",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

The merchant ID is missing

HTTP 400 Bad Request · INVALID_REQUEST · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "INVALID_REQUEST",
      "message": "Merchant ID is required",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

The payment ID is missing while building the request

HTTP 400 Bad Request · INVALID_REQUEST · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "INVALID_REQUEST",
      "message": "Payment ID is required",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

The capture amount is zero or negative while building the request

HTTP 400 Bad Request · INVALID_REQUEST · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "INVALID_REQUEST",
      "message": "Capture amount must be greater than zero",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

The payment is not found during capture validation

HTTP 400 Bad Request · INVALID_REQUEST · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "INVALID_REQUEST",
      "message": "Payment not found",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

The payment is not in a capturable state

HTTP 409 Conflict · INVALID_STATE · Retriable: No

{
  "errors": [
    {
      "category": "WORKFLOW",
      "code": "INVALID_STATE",
      "message": "Payment is not in a capturable state (current: <status>)",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

No amount remains available for capture

HTTP 400 Bad Request · INVALID_REQUEST · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "INVALID_REQUEST",
      "message": "No remaining amount available for capture",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

The resolved capture amount is zero or negative

HTTP 400 Bad Request · INVALID_REQUEST · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "INVALID_REQUEST",
      "message": "Capture amount must be greater than zero",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

The requested amount exceeds the remaining capturable amount

HTTP 400 Bad Request · INVALID_REQUEST · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "INVALID_REQUEST",
      "message": "Capture amount (<X> minor) exceeds remaining capturable amount (<Y> minor)",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

lite cannot start the payment operation

HTTP 503 Service Unavailable · WORKFLOW_SUBMISSION_FAILED · Retriable: Yes

{
  "errors": [
    {
      "category": "CONNECTION",
      "code": "WORKFLOW_SUBMISSION_FAILED",
      "message": "Payment orchestrator is temporarily unavailable",
      "retriable": true
    }
  ],
  "request_id": "<request-id>"
}

Void a payment

POST /api/v1/payments/:paymentId/void Also returned: missing merchant context, malformed request, field validation, and internal errors. Missing-payment and build-input errors match the capture operation.

The void request fails validation

HTTP 400 Bad Request · INVALID_REQUEST · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "INVALID_REQUEST",
      "message": "The request is malformed. Fix the JSON structure and resubmit.",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

The merchant is not allowed to void the payment

HTTP 403 Forbidden · FORBIDDEN · Retriable: No

{
  "errors": [
    {
      "category": "SETUP",
      "code": "FORBIDDEN",
      "message": "You do not have permission to perform this action.",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

The payment is not found

HTTP 404 Not Found · PAYMENT_NOT_FOUND · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "PAYMENT_NOT_FOUND",
      "message": "The payment was not found. Verify the payment ID.",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

The payment has already been voided, captured, or is otherwise in the wrong state

HTTP 409 Conflict · INVALID_STATE · Retriable: No

{
  "errors": [
    {
      "category": "WORKFLOW",
      "code": "INVALID_STATE",
      "message": "This operation is not allowed in the current state. Check the current status first.",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

The void or authorization is declined

HTTP 422 Unprocessable Entity · DECLINED · Retriable: No

{
  "errors": [
    {
      "category": "ISSUER",
      "code": "DECLINED",
      "message": "The transaction was declined. Ask the customer to try a different card.",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

The transaction is rejected for fraud

HTTP 422 Unprocessable Entity · FRAUD_DETECTED · Retriable: No

{
  "errors": [
    {
      "category": "FRAUD",
      "code": "FRAUD_DETECTED",
      "message": "The transaction was declined for security reasons. Do not retry.",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

The transaction is rejected by risk controls

HTTP 422 Unprocessable Entity · RISK_DECLINED · Retriable: No

{
  "errors": [
    {
      "category": "FRAUD",
      "code": "RISK_DECLINED",
      "message": "The transaction was declined by risk controls. Review in the dashboard.",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

3D Secure authentication fails

HTTP 422 Unprocessable Entity · AUTHENTICATION_FAILED · Retriable: No

{
  "errors": [
    {
      "category": "FRAUD",
      "code": "AUTHENTICATION_FAILED",
      "message": "3D Secure authentication failed. Ask the customer to try again or use a different card.",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

The 3D Secure service times out

HTTP 422 Unprocessable Entity · AUTHENTICATION_UNAVAILABLE · Retriable: Yes

{
  "errors": [
    {
      "category": "FRAUD",
      "code": "AUTHENTICATION_UNAVAILABLE",
      "message": "Authentication service is temporarily unavailable. Retry after a short delay.",
      "retriable": true
    }
  ],
  "request_id": "<request-id>"
}

An upstream service cannot be reached

HTTP 502 Bad Gateway · PROVIDER_CONNECTION_ERROR · Retriable: Yes

{
  "errors": [
    {
      "category": "CONNECTION",
      "code": "PROVIDER_CONNECTION_ERROR",
      "message": "A connection error occurred with the payment provider. Retry after a short delay.",
      "retriable": true
    }
  ],
  "request_id": "<request-id>"
}

An unexpected error occurs while voiding the payment

HTTP 500 Internal Server Error · INTERNAL_ERROR · Retriable: Yes

{
  "errors": [
    {
      "category": "SYSTEM",
      "code": "INTERNAL_ERROR",
      "message": "An unexpected error occurred. Retry with backoff. lite.sa has been alerted.",
      "retriable": true
    }
  ],
  "request_id": "<request-id>"
}

lite cannot submit or process the void request

HTTP 503 Service Unavailable · WORKFLOW_SUBMISSION_FAILED · Retriable: Yes

{
  "errors": [
    {
      "category": "CONNECTION",
      "code": "WORKFLOW_SUBMISSION_FAILED",
      "message": "Payment orchestrator is temporarily unavailable",
      "retriable": true
    }
  ],
  "request_id": "<request-id>"
}

Refund a payment

POST /api/v1/payments/:paymentId/refund Also returned: missing merchant context, malformed request, field validation, and internal errors. Missing-payment and build-input errors match the capture operation.

lite cannot load the payment state

HTTP 503 Service Unavailable · WORKFLOW_SUBMISSION_FAILED · Retriable: Yes

{
  "errors": [
    {
      "category": "CONNECTION",
      "code": "WORKFLOW_SUBMISSION_FAILED",
      "message": "Failed to load payment orchestration state",
      "retriable": true
    }
  ],
  "request_id": "<request-id>"
}

The payment does not exist or has not been captured

HTTP 400 Bad Request · INVALID_REQUEST · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "INVALID_REQUEST",
      "message": "Payment not found or not yet captured",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

The payment state does not contain the card brand required for the balance check

HTTP 400 Bad Request · INVALID_REQUEST · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "INVALID_REQUEST",
      "message": "Card brand is required for refund balance check",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

The payment is not in a refundable state

HTTP 409 Conflict · INVALID_STATE · Retriable: No

{
  "errors": [
    {
      "category": "WORKFLOW",
      "code": "INVALID_STATE",
      "message": "This payment is not in a state that allows for refunds (current: <status>)",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

No amount remains available for refund

HTTP 400 Bad Request · INVALID_REQUEST · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "INVALID_REQUEST",
      "message": "No remaining amount available for refund",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

The refund amount is zero or negative

HTTP 400 Bad Request · INVALID_REQUEST · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "INVALID_REQUEST",
      "message": "Refund amount must be greater than zero",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

The refund amount exceeds the remaining refundable amount

HTTP 400 Bad Request · INVALID_REQUEST · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "INVALID_REQUEST",
      "message": "Refund amount (<X>) exceeds remaining refundable amount (<Y>)",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

lite cannot start the payment operation

HTTP 503 Service Unavailable · WORKFLOW_SUBMISSION_FAILED · Retriable: Yes

{
  "errors": [
    {
      "category": "CONNECTION",
      "code": "WORKFLOW_SUBMISSION_FAILED",
      "message": "Payment orchestrator is temporarily unavailable",
      "retriable": true
    }
  ],
  "request_id": "<request-id>"
}

Extend an authorization

POST /api/v1/payments/:paymentId/extend-authorization Also returned: missing merchant context, malformed request, field validation, and internal errors. Missing-payment and build-input errors match the capture operation.

Authorization extension is disabled in the current environment

HTTP 500 Internal Server Error · INTERNAL_ERROR · Retriable: Yes

{
  "errors": [
    {
      "category": "SYSTEM",
      "code": "INTERNAL_ERROR",
      "message": "Authorization extension is not available in this environment",
      "retriable": true
    }
  ],
  "request_id": "<request-id>"
}

The payment is not found

HTTP 404 Not Found · PAYMENT_NOT_FOUND · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "PAYMENT_NOT_FOUND",
      "message": "The payment was not found. Verify the payment ID.",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

The payment is not in `AUTHORIZED` status

HTTP 409 Conflict · INVALID_STATE · Retriable: No

{
  "errors": [
    {
      "category": "WORKFLOW",
      "code": "INVALID_STATE",
      "message": "Authorization can only be extended for authorized payments",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

lite cannot start the payment operation

HTTP 503 Service Unavailable · WORKFLOW_SUBMISSION_FAILED · Retriable: Yes

{
  "errors": [
    {
      "category": "CONNECTION",
      "code": "WORKFLOW_SUBMISSION_FAILED",
      "message": "Payment orchestrator is temporarily unavailable",
      "retriable": true
    }
  ],
  "request_id": "<request-id>"
}

Retrieve a payment

GET /api/v1/payments/:paymentId GET /api/v1/payments/orders/:orderId This endpoint can also return the shared missing-merchant and internal errors.

The payment or order is not found

HTTP 404 Not Found · PAYMENT_NOT_FOUND · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "PAYMENT_NOT_FOUND",
      "message": "The payment was not found. Verify the payment ID.",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

List payments

GET /api/v1/payments This endpoint can also return the shared missing-merchant and internal errors. All query validation failures return 400 INVALID_FIELD_VALUE with retriable: false.

`page` or `pageSize` is not a positive integer

HTTP 400 Bad Request · INVALID_FIELD_VALUE · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "INVALID_FIELD_VALUE",
      "message": "page and pageSize must be positive integers",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

`pageSize` is greater than 100

HTTP 400 Bad Request · INVALID_FIELD_VALUE · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "INVALID_FIELD_VALUE",
      "message": "pageSize must not exceed 100",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

`status` is unsupported

HTTP 400 Bad Request · INVALID_FIELD_VALUE · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "INVALID_FIELD_VALUE",
      "message": "status must be one of: CREATED, PENDING, AUTHORIZED, FAILED, EXPIRED, AUTHORIZATION_REVERSED, VOIDED, PARTIALLY_CAPTURED, CAPTURED, REFUNDED, DISPUTED, DISPUTE_CHALLENGED, ARBITRATION_INITIATED, ARBITRATION_LOST, CHARGEDBACK, REQUIRES_ACTION",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

`paymentMethod` is unsupported

HTTP 400 Bad Request · INVALID_FIELD_VALUE · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "INVALID_FIELD_VALUE",
      "message": "paymentMethod must be one of: CARD, APPLE_PAY, GOOGLE_PAY, SAMSUNG_PAY, MDES, SCOF, VTS, VCOF, IBAN",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

`fromDate` is invalid

HTTP 400 Bad Request · INVALID_FIELD_VALUE · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "INVALID_FIELD_VALUE",
      "message": "fromDate must be a valid ISO date string",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

`toDate` is invalid

HTTP 400 Bad Request · INVALID_FIELD_VALUE · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "INVALID_FIELD_VALUE",
      "message": "toDate must be a valid ISO date string",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

`fromDate` is later than `toDate`

HTTP 400 Bad Request · INVALID_FIELD_VALUE · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "INVALID_FIELD_VALUE",
      "message": "fromDate must be earlier than toDate",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

POS payments

/api/v1/pos/payments Also returned: missing authentication context, malformed request, field validation, and internal errors.

Initialize a POS payment

POST /api/v1/pos/payments/init

The merchant ID is missing

HTTP 400 Bad Request · INVALID_REQUEST · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "INVALID_REQUEST",
      "message": "Merchant ID is required",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

The terminal ID is missing for a merchant-initiated payment

HTTP 400 Bad Request · INVALID_REQUEST · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "INVALID_REQUEST",
      "message": "Terminal ID is required for merchant-initiated payments",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

The amount or currency is invalid

HTTP 400 Bad Request · INVALID_REQUEST · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "INVALID_REQUEST",
      "message": "Invalid payment amount or currency",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

lite cannot start the payment operation

HTTP 503 Service Unavailable · WORKFLOW_SUBMISSION_FAILED · Retriable: Yes

{
  "errors": [
    {
      "category": "CONNECTION",
      "code": "WORKFLOW_SUBMISSION_FAILED",
      "message": "Payment orchestrator is temporarily unavailable",
      "retriable": true
    }
  ],
  "request_id": "<request-id>"
}

Update a POS payment

POST /api/v1/pos/payments/:paymentId/update

`provider` is missing

HTTP 400 Bad Request · INVALID_REQUEST · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "INVALID_REQUEST",
      "message": "The request is malformed. Fix the JSON structure and resubmit.",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

`raw_receipt` is missing when `error` is not provided

HTTP 400 Bad Request · INVALID_REQUEST · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "INVALID_REQUEST",
      "message": "raw_receipt is required when error is not provided",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

The provider is unsupported

HTTP 400 Bad Request · INVALID_REQUEST · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "INVALID_REQUEST",
      "message": "The request is malformed. Fix the JSON structure and resubmit.",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

The receipt does not match the expected schema

HTTP 400 Bad Request · INVALID_REQUEST · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "INVALID_REQUEST",
      "message": "The request is malformed. Fix the JSON structure and resubmit.",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

The merchant ID is missing

HTTP 400 Bad Request · INVALID_REQUEST · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "INVALID_REQUEST",
      "message": "Merchant ID is required",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

The terminal ID is missing for a merchant-initiated payment

HTTP 400 Bad Request · INVALID_REQUEST · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "INVALID_REQUEST",
      "message": "Terminal ID is required for merchant-initiated payments",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

The amount or currency is invalid

HTTP 400 Bad Request · INVALID_REQUEST · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "INVALID_REQUEST",
      "message": "Invalid payment amount or currency",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

The payment update fails with a known API error

Response: Varies
Retriable: Varies
Message: lite returns the underlying error’s HTTP status, code, and message unchanged.

lite cannot process the payment update

HTTP 503 Service Unavailable · WORKFLOW_SUBMISSION_FAILED · Retriable: Yes

{
  "errors": [
    {
      "category": "CONNECTION",
      "code": "WORKFLOW_SUBMISSION_FAILED",
      "message": "Payment orchestrator is temporarily unavailable",
      "retriable": true
    }
  ],
  "request_id": "<request-id>"
}

Retrieve the latest POS payment

GET /api/v1/pos/payments/latest

No payment exists for the terminal

HTTP 404 Not Found · PAYMENT_NOT_FOUND · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "PAYMENT_NOT_FOUND",
      "message": "No POS payment found for terminal",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

GET /api/v1/pos/payments/operations and GET /api/v1/pos/payments/transactions return only the shared authentication-context, query-validation, and internal errors documented above.

3D Secure

3D Secure API

/api/v1/threeds This endpoint can also return the shared malformed-request, field-validation, and internal errors. These endpoints do not use the merchant guard.

lite cannot start 3D Secure authentication

HTTP 500 Internal Server Error · INTERNAL_ERROR · Retriable: Yes

{
  "errors": [
    {
      "category": "SYSTEM",
      "code": "INTERNAL_ERROR",
      "message": "Failed to process 3DS authentication",
      "retriable": true
    }
  ],
  "request_id": "<request-id>"
}

The 3D Secure record is not found

HTTP 404 Not Found · ENTITY_NOT_FOUND · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "ENTITY_NOT_FOUND",
      "message": "3D Secure authentication record was not found.",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

The 3D Secure record is not found during confirmation

HTTP 404 Not Found · ENTITY_NOT_FOUND · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "ENTITY_NOT_FOUND",
      "message": "3D Secure authentication record was not found.",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

The authentication is not in challenge state

HTTP 409 Conflict · INVALID_STATE · Retriable: No

{
  "errors": [
    {
      "category": "WORKFLOW",
      "code": "INVALID_STATE",
      "message": "3DS authentication is not in CHALLENGE_REQUIRED status. Current status: <status>",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

lite cannot retrieve the 3D Secure status

HTTP 500 Internal Server Error · INTERNAL_ERROR · Retriable: Yes

{
  "errors": [
    {
      "category": "SYSTEM",
      "code": "INTERNAL_ERROR",
      "message": "Failed to get 3DS status",
      "retriable": true
    }
  ],
  "request_id": "<request-id>"
}

lite cannot confirm the 3D Secure challenge

HTTP 500 Internal Server Error · INTERNAL_ERROR · Retriable: Yes

{
  "errors": [
    {
      "category": "SYSTEM",
      "code": "INTERNAL_ERROR",
      "message": "Failed to confirm 3DS",
      "retriable": true
    }
  ],
  "request_id": "<request-id>"
}

The 3D Secure status request returns another API error

Response: Varies
Retriable: Varies
Message: lite returns the underlying error’s HTTP status, code, and message unchanged.

Browser challenge

/v1/threeds/redirect These are browser-facing routes. Some errors do not use the standard API envelope.

`GET /challenge`

The redirect token is invalid or expired

HTTP 401 Unauthorized · UNAUTHORIZED · Retriable: No

{
  "errors": [
    {
      "category": "SETUP",
      "code": "UNAUTHORIZED",
      "message": "Authentication is required to access this resource.",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

The 3D Secure record is not found

HTTP 404 Not Found · ENTITY_NOT_FOUND · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "ENTITY_NOT_FOUND",
      "message": "The entity was not found. Verify the entity ID in the dashboard.",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

The 3D Secure request is invalid

HTTP 400 Bad Request · INVALID_REQUEST · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "INVALID_REQUEST",
      "message": "The request is malformed. Fix the JSON structure and resubmit.",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

The authentication is not in the required state, or challenge data is missing

HTTP 409 Conflict · INVALID_STATE · Retriable: No

{
  "errors": [
    {
      "category": "WORKFLOW",
      "code": "INVALID_STATE",
      "message": "3D Secure authentication is not in the required state for this operation.",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

`POST /confirm`

When the token is invalid, the route renders an HTML error page with HTTP 200 and errorCode: invalid_token. It does not return JSON.

`GET /status`

This route returns raw JSON rather than the standard error envelope:

HTTP status	Body
401	`{ "error": "Invalid or expired token" }`
404	`{ "error": "3DS authentication not found" }`
500	`{ "error": "Internal server error" }`

Payment Links

Manage Payment Links

/api/v1/payment-links Also returned: missing authentication context, field validation, and internal errors.

`POST /`: `mode` and `max_uses` are inconsistent

HTTP 400 Bad Request · INVALID_REQUEST · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "INVALID_REQUEST",
      "message": "The request is malformed. Fix the JSON structure and resubmit.",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

`PATCH /:id`: the requested status transition is not allowed

HTTP 400 Bad Request · INVALID_REQUEST · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "INVALID_REQUEST",
      "message": "The request is malformed. Fix the JSON structure and resubmit.",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

`PATCH /:id`: the link has already been used

HTTP 400 Bad Request · INVALID_REQUEST · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "INVALID_REQUEST",
      "message": "The request is malformed. Fix the JSON structure and resubmit.",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

`POST /`: `merchant_reference_id` already exists

HTTP 409 Conflict · DUPLICATE_REQUEST · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "DUPLICATE_REQUEST",
      "message": "A request with this idempotency key already exists. Use the original response or a new key.",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

`GET /:id`, `PATCH /:id`, or `GET /:id/consumptions`: the link does not exist or belongs to another merchant

HTTP 404 Not Found · ENTITY_NOT_FOUND · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "ENTITY_NOT_FOUND",
      "message": "The entity was not found. Verify the entity ID in the dashboard.",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

Open a Payment Link

GET /pay/:token This is a customer-facing route. When a payment-link status URL is configured, errors redirect to that page with one of these query values:

?status=not_found
?status=expired
?status=unavailable
?status=error

No JSON body is returned in this channel. Without a status URL, the route returns JSON errors:

The link does not exist

HTTP 404 Not Found · ENTITY_NOT_FOUND · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "ENTITY_NOT_FOUND",
      "message": "The entity was not found. Verify the entity ID in the dashboard.",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

A single-use link currently has no available slot

HTTP 409 Conflict · DUPLICATE_REQUEST · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "DUPLICATE_REQUEST",
      "message": "A request with this idempotency key already exists. Use the original response or a new key.",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

lite cannot create the checkout session

HTTP 502 Bad Gateway · PROVIDER_CONNECTION_ERROR · Retriable: Yes

{
  "errors": [
    {
      "category": "CONNECTION",
      "code": "PROVIDER_CONNECTION_ERROR",
      "message": "A connection error occurred with the payment provider. Retry after a short delay.",
      "retriable": true
    }
  ],
  "request_id": "<request-id>"
}

The link is expired, paid, disabled, or has reached its usage limit

HTTP 500 Internal Server Error · INTERNAL_ERROR · Retriable: Yes

{
  "errors": [
    {
      "category": "SYSTEM",
      "code": "INTERNAL_ERROR",
      "message": "An unexpected error occurred. Retry with backoff. lite.sa has been alerted.",
      "retriable": true
    }
  ],
  "request_id": "<request-id>"
}

The consumption record cannot be created

HTTP 500 Internal Server Error · INTERNAL_ERROR · Retriable: Yes

{
  "errors": [
    {
      "category": "SYSTEM",
      "code": "INTERNAL_ERROR",
      "message": "An unexpected error occurred. Retry with backoff. lite.sa has been alerted.",
      "retriable": true
    }
  ],
  "request_id": "<request-id>"
}

Instruments

/api/v1/instruments Also returned: missing authentication context, malformed request, field validation, and internal errors.

Create an instrument

POST /api/v1/instruments Field-level validation can return several errors in one response. Missing fields use MISSING_REQUIRED_FIELD; other constraints use INVALID_FIELD_VALUE.

Field validation fails

HTTP 400 Bad Request · MISSING_REQUIRED_FIELD or INVALID_FIELD_VALUE · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "MISSING_REQUIRED_FIELD",
      "message": "Invalid input: expected string, received undefined",
      "field": "holder_id",
      "retriable": false
    },
    {
      "category": "VALIDATION",
      "code": "INVALID_FIELD_VALUE",
      "message": "cardNumber must be 12-19 digits",
      "field": "pan_data.card_number",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

Field	Returned message
`pan_data.card_number`	`cardNumber must be 12-19 digits`
`pan_data.expiry_month`	`expiryMonth must be a valid month in MM format`
`pan_data.expiry_year`	`expiryYear must be 2 digits (YY)`
`pan_data.cvc`	`cvc must be 3 or 4 digits`
`pan_data.holder_name`	`holderName must contain only letters and spaces`
`pan_data`	`One of panData, paymentToken, or data must be provided`
Any missing required field	A validator message such as `Invalid input: expected string, received undefined`

Other create errors:

The payment method is unsupported

HTTP 400 Bad Request · INVALID_REQUEST · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "INVALID_REQUEST",
      "message": "Unsupported payment method",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

Apple Pay `data` is not valid JSON

HTTP 400 Bad Request · INVALID_REQUEST · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "INVALID_REQUEST",
      "message": "Invalid data format. Expected valid JSON string.",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

The payment token cannot be decrypted

HTTP 400 Bad Request · INVALID_REQUEST · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "INVALID_REQUEST",
      "message": "Failed to decrypt payment token. Payment token decryption failed or returned invalid data.",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

lite cannot process the Apple Pay data

HTTP 400 Bad Request · INVALID_REQUEST · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "INVALID_REQUEST",
      "message": "Failed to map payment data to CDMA format",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

Card details are missing

HTTP 400 Bad Request · INVALID_REQUEST · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "INVALID_REQUEST",
      "message": "PAN data is required",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

lite cannot tokenize or save the instrument

HTTP 500 Internal Server Error · INTERNAL_ERROR · Retriable: Yes

{
  "errors": [
    {
      "category": "SYSTEM",
      "code": "INTERNAL_ERROR",
      "message": "An unexpected error occurred. Retry with backoff. lite.sa has been alerted.",
      "retriable": true
    }
  ],
  "request_id": "<request-id>"
}

lite cannot create the instrument

HTTP 500 Internal Server Error · INTERNAL_ERROR · Retriable: Yes

{
  "errors": [
    {
      "category": "SYSTEM",
      "code": "INTERNAL_ERROR",
      "message": "Failed to CreateInstrument",
      "retriable": true
    }
  ],
  "request_id": "<request-id>"
}

A duplicate fingerprint with future_usage returns the existing instrument with HTTP 201. It is not returned as an error.

List instruments

GET /api/v1/instruments

The lookup input fails validation

Response: 400 MISSING_REQUIRED_FIELD or 400 INVALID_FIELD_VALUE
Retriable: NoField validation can return one error per invalid field:

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "MISSING_REQUIRED_FIELD",
      "message": "<field> should not be empty",
      "field": "<field>",
      "retriable": false
    },
    {
      "category": "VALIDATION",
      "code": "INVALID_FIELD_VALUE",
      "message": "<validation message>",
      "field": "<field>",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

lite cannot list instruments

HTTP 500 Internal Server Error · INTERNAL_ERROR · Retriable: Yes

{
  "errors": [
    {
      "category": "SYSTEM",
      "code": "INTERNAL_ERROR",
      "message": "Failed to LookupInstruments",
      "retriable": true
    }
  ],
  "request_id": "<request-id>"
}

Retrieve an instrument

GET /api/v1/instruments/:id

The instrument is not found

HTTP 404 Not Found · ENTITY_NOT_FOUND · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "ENTITY_NOT_FOUND",
      "message": "The requested instrument was not found.",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

The instrument belongs to another merchant

HTTP 403 Forbidden · ENTITY_ACCESS_DENIED · Retriable: No

{
  "errors": [
    {
      "category": "SETUP",
      "code": "ENTITY_ACCESS_DENIED",
      "message": "Access denied to this instrument.",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

lite cannot retrieve the instrument

HTTP 500 Internal Server Error · INTERNAL_ERROR · Retriable: Yes

{
  "errors": [
    {
      "category": "SYSTEM",
      "code": "INTERNAL_ERROR",
      "message": "Failed to GetInstrumentById",
      "retriable": true
    }
  ],
  "request_id": "<request-id>"
}

Update an instrument

PUT /api/v1/instruments/action

`instrument_id` or `action_type` fails validation

Response: 400 MISSING_REQUIRED_FIELD or 400 INVALID_FIELD_VALUE
Retriable: NoField validation can return one error per invalid field:

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "MISSING_REQUIRED_FIELD",
      "message": "<field> should not be empty",
      "field": "<field>",
      "retriable": false
    },
    {
      "category": "VALIDATION",
      "code": "INVALID_FIELD_VALUE",
      "message": "<validation message>",
      "field": "<field>",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

The instrument is not found

HTTP 404 Not Found · ENTITY_NOT_FOUND · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "ENTITY_NOT_FOUND",
      "message": "The requested instrument was not found.",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

The requested action is not publicly supported

HTTP 400 Bad Request · INVALID_REQUEST · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "INVALID_REQUEST",
      "message": "<Action description> is not currently supported",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

The action is not allowed in the instrument's current state

HTTP 409 Conflict · INVALID_STATE · Retriable: No

{
  "errors": [
    {
      "category": "WORKFLOW",
      "code": "INVALID_STATE",
      "message": "This operation is not allowed in the current state. Check the current status first.",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

lite cannot update the instrument

HTTP 500 Internal Server Error · INTERNAL_ERROR · Retriable: Yes

{
  "errors": [
    {
      "category": "SYSTEM",
      "code": "INTERNAL_ERROR",
      "message": "An unexpected error occurred. Retry with backoff. lite.sa has been alerted.",
      "retriable": true
    }
  ],
  "request_id": "<request-id>"
}

An action that leaves the instrument in its existing state returns success rather than an error.

Device payments

/api/v1/device-payment/* merchant-mapping/* Also returned: missing authentication context, field validation, and internal errors.

The provider name, CSR, session, or channel data is invalid

HTTP 400 Bad Request · INVALID_REQUEST · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "INVALID_REQUEST",
      "message": "The request is malformed. Fix the JSON structure and resubmit.",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

Provider-session authentication fails

HTTP 401 Unauthorized · UNAUTHORIZED · Retriable: No

{
  "errors": [
    {
      "category": "SETUP",
      "code": "UNAUTHORIZED",
      "message": "Authentication is required to access this resource.",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

The operation is forbidden

HTTP 403 Forbidden · FORBIDDEN · Retriable: No

{
  "errors": [
    {
      "category": "SETUP",
      "code": "FORBIDDEN",
      "message": "You do not have permission to perform this action.",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

A mapping, credential, or provider is not found

HTTP 404 Not Found · ENTITY_NOT_FOUND · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "ENTITY_NOT_FOUND",
      "message": "The entity was not found. Verify the entity ID in the dashboard.",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

The mapping already exists

HTTP 409 Conflict · DUPLICATE_REQUEST · Retriable: No

{
  "errors": [
    {
      "category": "VALIDATION",
      "code": "DUPLICATE_REQUEST",
      "message": "A request with this idempotency key already exists. Use the original response or a new key.",
      "retriable": false
    }
  ],
  "request_id": "<request-id>"
}

An upstream device-payment request fails

HTTP 502 Bad Gateway · PROVIDER_CONNECTION_ERROR · Retriable: Yes

{
  "errors": [
    {
      "category": "CONNECTION",
      "code": "PROVIDER_CONNECTION_ERROR",
      "message": "A connection error occurred with the payment provider. Retry after a short delay.",
      "retriable": true
    }
  ],
  "request_id": "<request-id>"
}

The payment provider is unavailable

HTTP 503 Service Unavailable · PROVIDER_UNAVAILABLE · Retriable: Yes

{
  "errors": [
    {
      "category": "CONNECTION",
      "code": "PROVIDER_UNAVAILABLE",
      "message": "The payment provider is temporarily unavailable. Retry or use a fallback.",
      "retriable": true
    }
  ],
  "request_id": "<request-id>"
}

The payment provider times out

HTTP 504 Gateway Timeout · GATEWAY_TIMEOUT · Retriable: Yes

{
  "errors": [
    {
      "category": "CONNECTION",
      "code": "GATEWAY_TIMEOUT",
      "message": "The payment provider timed out. Retry after a short delay.",
      "retriable": true
    }
  ],
  "request_id": "<request-id>"
}

An internal error occurs

HTTP 500 Internal Server Error · INTERNAL_ERROR · Retriable: Yes

{
  "errors": [
    {
      "category": "SYSTEM",
      "code": "INTERNAL_ERROR",
      "message": "An unexpected error occurred. Retry with backoff. lite.sa has been alerted.",
      "retriable": true
    }
  ],
  "request_id": "<request-id>"
}

Accept Payments

Tokenization

Account

Read an error

Validation errors

HTTP status codes

Error categories

Error codes

Retry failed requests

Errors by API

Common errors

Payments

Authorize a payment

Capture a payment

Void a payment

Refund a payment

Extend an authorization

Retrieve a payment

List payments

POS payments

Initialize a POS payment

Update a POS payment

Retrieve the latest POS payment

3D Secure

3D Secure API

Browser challenge

`GET /challenge`

`POST /confirm`

`GET /status`

Payment Links

Manage Payment Links

Open a Payment Link

Instruments

Create an instrument

List instruments

Retrieve an instrument

Update an instrument

Device payments

​Read an error

​Validation errors

​HTTP status codes

​Error categories

​Error codes

​Retry failed requests

​Errors by API

​Common errors

​Payments

​Authorize a payment

​Capture a payment

​Void a payment

​Refund a payment

​Extend an authorization

​Retrieve a payment

​List payments

​POS payments

​Initialize a POS payment

​Update a POS payment

​Retrieve the latest POS payment

​3D Secure

​3D Secure API

​Browser challenge

GET /challenge

POST /confirm

GET /status

​Payment Links

​Manage Payment Links

​Open a Payment Link

​Instruments

​Create an instrument

​List instruments

​Retrieve an instrument

​Update an instrument

​Device payments

Read an error

Validation errors

HTTP status codes

Error categories

Error codes

Retry failed requests

Errors by API

Common errors

Payments

Authorize a payment

Capture a payment

Void a payment

Refund a payment

Extend an authorization

Retrieve a payment

List payments

POS payments

Initialize a POS payment

Update a POS payment

Retrieve the latest POS payment

3D Secure

3D Secure API

Browser challenge

`GET /challenge`

`POST /confirm`

`GET /status`

Payment Links

Manage Payment Links

Open a Payment Link

Instruments

Create an instrument

List instruments

Retrieve an instrument

Update an instrument

Device payments