> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lite.sa/llms.txt
> Use this file to discover all available pages before exploring further.

# API errors

> Understand lite error responses and find the errors returned by each API.

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`.

```json theme={null}
{
  "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.             |

<Note>
  Fields such as `retry_after_seconds`, `documentation_url`, `routing_attempts`, `error_id`, `business_id`, and `entity_id` are not currently returned.
</Note>

## Validation errors

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

```json theme={null}
{
  "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.

<AccordionGroup>
  <Accordion title="Merchant context is missing">
    **Returned by:** Payment APIs under `/api/v1/payments/*`

    **HTTP 401 Unauthorized** · `UNAUTHORIZED` · Retriable: **No**

    ```json theme={null}
    {
      "errors": [
        {
          "category": "SETUP",
          "code": "UNAUTHORIZED",
          "message": "Merchant context is required",
          "retriable": false
        }
      ],
      "request_id": "<request-id>"
    }
    ```
  </Accordion>

  <Accordion title="Authentication, merchant, or terminal context is missing">
    **Returned by:** Instruments, POS, Payment Links, device payments, and some 3D Secure browser flows

    **HTTP 401 Unauthorized** · `UNAUTHORIZED` · Retriable: **No**

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

  <Accordion title="The request uses camelCase or contains unknown keys where snake_case is expected">
    **Returned by:** Payment and instrument APIs

    **HTTP 400 Bad Request** · `INVALID_REQUEST` · Retriable: **No**

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

  <Accordion title="A required request field is missing">
    **Returned by:** Endpoints with request validation

    **HTTP 400 Bad Request** · `MISSING_REQUIRED_FIELD` · Retriable: **No**

    ```json theme={null}
    {
      "errors": [
        {
          "category": "VALIDATION",
          "code": "MISSING_REQUIRED_FIELD",
          "message": "<field> should not be empty",
          "field": "<field>",
          "retriable": false
        }
      ],
      "request_id": "<request-id>"
    }
    ```
  </Accordion>

  <Accordion title="A request field fails validation">
    **Returned by:** Endpoints with request validation

    **HTTP 400 Bad Request** · `INVALID_FIELD_VALUE` · Retriable: **No**

    ```json theme={null}
    {
      "errors": [
        {
          "category": "VALIDATION",
          "code": "INVALID_FIELD_VALUE",
          "message": "<validation message>",
          "field": "<field>",
          "retriable": false
        }
      ],
      "request_id": "<request-id>"
    }
    ```
  </Accordion>

  <Accordion title="An unhandled failure occurs">
    **Returned by:** Payment and instrument APIs

    **HTTP 500 Internal Server Error** · `INTERNAL_ERROR` · Retriable: **Yes**

    ```json theme={null}
    {
      "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>"
    }
    ```
  </Accordion>
</AccordionGroup>

### Payments

#### Authorize a payment

`POST /api/v1/payments`

Also returned: missing merchant context, malformed request, field validation, and internal errors.

<AccordionGroup>
  <Accordion title="The line items, VAT, and shipping total do not match the authorization amount">
    **HTTP 400 Bad Request** · `INVALID_AMOUNT` · Retriable: **No**

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

  <Accordion title="The instrument ID is empty or is not a valid UUID">
    **HTTP 400 Bad Request** · `INVALID_REQUEST` · Retriable: **No**

    ```json theme={null}
    {
      "errors": [
        {
          "category": "VALIDATION",
          "code": "INVALID_REQUEST",
          "message": "Payment instrument id is invalid or malformed",
          "retriable": false
        }
      ],
      "request_id": "<request-id>"
    }
    ```
  </Accordion>

  <Accordion title="The merchant ID is missing from the payment input">
    **HTTP 400 Bad Request** · `INVALID_REQUEST` · Retriable: **No**

    ```json theme={null}
    {
      "errors": [
        {
          "category": "VALIDATION",
          "code": "INVALID_REQUEST",
          "message": "Merchant ID is required",
          "retriable": false
        }
      ],
      "request_id": "<request-id>"
    }
    ```
  </Accordion>

  <Accordion title="The amount or currency is invalid">
    **HTTP 400 Bad Request** · `INVALID_REQUEST` · Retriable: **No**

    ```json theme={null}
    {
      "errors": [
        {
          "category": "VALIDATION",
          "code": "INVALID_REQUEST",
          "message": "Invalid payment amount or currency",
          "retriable": false
        }
      ],
      "request_id": "<request-id>"
    }
    ```
  </Accordion>

  <Accordion title="The terminal ID is missing for a merchant-initiated POS payment">
    **HTTP 400 Bad Request** · `INVALID_REQUEST` · Retriable: **No**

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

  <Accordion title="The payment token does not exist or was deleted">
    **HTTP 404 Not Found** · `TOKEN_NOT_FOUND` · Retriable: **No**

    ```json theme={null}
    {
      "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>"
    }
    ```
  </Accordion>

  <Accordion title="The payment token has expired">
    **HTTP 422 Unprocessable Entity** · `EXPIRED_TOKEN` · Retriable: **No**

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

  <Accordion title="The payment token is not active">
    **HTTP 422 Unprocessable Entity** · `INVALID_TOKEN` · Retriable: **No**

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

  <Accordion title="lite cannot resolve the payment instrument">
    **HTTP 422 Unprocessable Entity** · `INVALID_TOKEN` · Retriable: **No**

    ```json theme={null}
    {
      "errors": [
        {
          "category": "INSTRUMENT",
          "code": "INVALID_TOKEN",
          "message": "Invalid payment instrument",
          "retriable": false
        }
      ],
      "request_id": "<request-id>"
    }
    ```
  </Accordion>

  <Accordion title="A payment instrument with the same details already exists">
    **HTTP 409 Conflict** · `DUPLICATE_ENTITY` · Retriable: **No**

    ```json theme={null}
    {
      "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>"
    }
    ```
  </Accordion>

  <Accordion title="A request with the same order reference is already being processed">
    **HTTP 409 Conflict** · `DUPLICATE_REQUEST` · Retriable: **No**

    ```json theme={null}
    {
      "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>"
    }
    ```
  </Accordion>

  <Accordion title="The payment instrument lookup times out">
    **HTTP 504 Gateway Timeout** · `PROVIDER_TIMEOUT` · Retriable: **Yes**

    ```json theme={null}
    {
      "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>"
    }
    ```
  </Accordion>

  <Accordion title="The payment instrument lookup fails because of a connection error">
    **HTTP 502 Bad Gateway** · `PROVIDER_CONNECTION_ERROR` · Retriable: **Yes**

    ```json theme={null}
    {
      "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>"
    }
    ```
  </Accordion>

  <Accordion title="lite cannot start the payment operation">
    **HTTP 503 Service Unavailable** · `WORKFLOW_SUBMISSION_FAILED` · Retriable: **Yes**

    ```json theme={null}
    {
      "errors": [
        {
          "category": "CONNECTION",
          "code": "WORKFLOW_SUBMISSION_FAILED",
          "message": "Payment orchestrator is temporarily unavailable",
          "retriable": true
        }
      ],
      "request_id": "<request-id>"
    }
    ```
  </Accordion>

  <Accordion title="The original idempotent request is still processing when the wait period ends">
    **HTTP 500 Internal Server Error** · `INTERNAL_ERROR` · Retriable: **Yes**

    ```json theme={null}
    {
      "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>"
    }
    ```
  </Accordion>

  <Accordion title="An unexpected error occurs while resolving the payment instrument">
    **HTTP 500 Internal Server Error** · `INTERNAL_ERROR` · Retriable: **Yes**

    ```json theme={null}
    {
      "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>"
    }
    ```
  </Accordion>
</AccordionGroup>

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.

<AccordionGroup>
  <Accordion title="`paymentId` is missing">
    **HTTP 400 Bad Request** · `MISSING_REQUIRED_FIELD` · Retriable: **No**

    ```json theme={null}
    {
      "errors": [
        {
          "category": "VALIDATION",
          "code": "MISSING_REQUIRED_FIELD",
          "message": "Payment ID is required",
          "retriable": false
        }
      ],
      "request_id": "<request-id>"
    }
    ```
  </Accordion>

  <Accordion title="The payment is not found for the merchant">
    **HTTP 404 Not Found** · `PAYMENT_NOT_FOUND` · Retriable: **No**

    ```json theme={null}
    {
      "errors": [
        {
          "category": "VALIDATION",
          "code": "PAYMENT_NOT_FOUND",
          "message": "Payment not found",
          "retriable": false
        }
      ],
      "request_id": "<request-id>"
    }
    ```
  </Accordion>

  <Accordion title="The merchant ID is missing">
    **HTTP 400 Bad Request** · `INVALID_REQUEST` · Retriable: **No**

    ```json theme={null}
    {
      "errors": [
        {
          "category": "VALIDATION",
          "code": "INVALID_REQUEST",
          "message": "Merchant ID is required",
          "retriable": false
        }
      ],
      "request_id": "<request-id>"
    }
    ```
  </Accordion>

  <Accordion title="The payment ID is missing while building the request">
    **HTTP 400 Bad Request** · `INVALID_REQUEST` · Retriable: **No**

    ```json theme={null}
    {
      "errors": [
        {
          "category": "VALIDATION",
          "code": "INVALID_REQUEST",
          "message": "Payment ID is required",
          "retriable": false
        }
      ],
      "request_id": "<request-id>"
    }
    ```
  </Accordion>

  <Accordion title="The capture amount is zero or negative while building the request">
    **HTTP 400 Bad Request** · `INVALID_REQUEST` · Retriable: **No**

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

  <Accordion title="The payment is not found during capture validation">
    **HTTP 400 Bad Request** · `INVALID_REQUEST` · Retriable: **No**

    ```json theme={null}
    {
      "errors": [
        {
          "category": "VALIDATION",
          "code": "INVALID_REQUEST",
          "message": "Payment not found",
          "retriable": false
        }
      ],
      "request_id": "<request-id>"
    }
    ```
  </Accordion>

  <Accordion title="The payment is not in a capturable state">
    **HTTP 409 Conflict** · `INVALID_STATE` · Retriable: **No**

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

  <Accordion title="No amount remains available for capture">
    **HTTP 400 Bad Request** · `INVALID_REQUEST` · Retriable: **No**

    ```json theme={null}
    {
      "errors": [
        {
          "category": "VALIDATION",
          "code": "INVALID_REQUEST",
          "message": "No remaining amount available for capture",
          "retriable": false
        }
      ],
      "request_id": "<request-id>"
    }
    ```
  </Accordion>

  <Accordion title="The resolved capture amount is zero or negative">
    **HTTP 400 Bad Request** · `INVALID_REQUEST` · Retriable: **No**

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

  <Accordion title="The requested amount exceeds the remaining capturable amount">
    **HTTP 400 Bad Request** · `INVALID_REQUEST` · Retriable: **No**

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

  <Accordion title="lite cannot start the payment operation">
    **HTTP 503 Service Unavailable** · `WORKFLOW_SUBMISSION_FAILED` · Retriable: **Yes**

    ```json theme={null}
    {
      "errors": [
        {
          "category": "CONNECTION",
          "code": "WORKFLOW_SUBMISSION_FAILED",
          "message": "Payment orchestrator is temporarily unavailable",
          "retriable": true
        }
      ],
      "request_id": "<request-id>"
    }
    ```
  </Accordion>
</AccordionGroup>

#### 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.

<AccordionGroup>
  <Accordion title="The void request fails validation">
    **HTTP 400 Bad Request** · `INVALID_REQUEST` · Retriable: **No**

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

  <Accordion title="The merchant is not allowed to void the payment">
    **HTTP 403 Forbidden** · `FORBIDDEN` · Retriable: **No**

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

  <Accordion title="The payment is not found">
    **HTTP 404 Not Found** · `PAYMENT_NOT_FOUND` · Retriable: **No**

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

  <Accordion title="The payment has already been voided, captured, or is otherwise in the wrong state">
    **HTTP 409 Conflict** · `INVALID_STATE` · Retriable: **No**

    ```json theme={null}
    {
      "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>"
    }
    ```
  </Accordion>

  <Accordion title="The void or authorization is declined">
    **HTTP 422 Unprocessable Entity** · `DECLINED` · Retriable: **No**

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

  <Accordion title="The transaction is rejected for fraud">
    **HTTP 422 Unprocessable Entity** · `FRAUD_DETECTED` · Retriable: **No**

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

  <Accordion title="The transaction is rejected by risk controls">
    **HTTP 422 Unprocessable Entity** · `RISK_DECLINED` · Retriable: **No**

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

  <Accordion title="3D Secure authentication fails">
    **HTTP 422 Unprocessable Entity** · `AUTHENTICATION_FAILED` · Retriable: **No**

    ```json theme={null}
    {
      "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>"
    }
    ```
  </Accordion>

  <Accordion title="The 3D Secure service times out">
    **HTTP 422 Unprocessable Entity** · `AUTHENTICATION_UNAVAILABLE` · Retriable: **Yes**

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

  <Accordion title="An upstream service cannot be reached">
    **HTTP 502 Bad Gateway** · `PROVIDER_CONNECTION_ERROR` · Retriable: **Yes**

    ```json theme={null}
    {
      "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>"
    }
    ```
  </Accordion>

  <Accordion title="An unexpected error occurs while voiding the payment">
    **HTTP 500 Internal Server Error** · `INTERNAL_ERROR` · Retriable: **Yes**

    ```json theme={null}
    {
      "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>"
    }
    ```
  </Accordion>

  <Accordion title="lite cannot submit or process the void request">
    **HTTP 503 Service Unavailable** · `WORKFLOW_SUBMISSION_FAILED` · Retriable: **Yes**

    ```json theme={null}
    {
      "errors": [
        {
          "category": "CONNECTION",
          "code": "WORKFLOW_SUBMISSION_FAILED",
          "message": "Payment orchestrator is temporarily unavailable",
          "retriable": true
        }
      ],
      "request_id": "<request-id>"
    }
    ```
  </Accordion>
</AccordionGroup>

#### 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.

<AccordionGroup>
  <Accordion title="lite cannot load the payment state">
    **HTTP 503 Service Unavailable** · `WORKFLOW_SUBMISSION_FAILED` · Retriable: **Yes**

    ```json theme={null}
    {
      "errors": [
        {
          "category": "CONNECTION",
          "code": "WORKFLOW_SUBMISSION_FAILED",
          "message": "Failed to load payment orchestration state",
          "retriable": true
        }
      ],
      "request_id": "<request-id>"
    }
    ```
  </Accordion>

  <Accordion title="The payment does not exist or has not been captured">
    **HTTP 400 Bad Request** · `INVALID_REQUEST` · Retriable: **No**

    ```json theme={null}
    {
      "errors": [
        {
          "category": "VALIDATION",
          "code": "INVALID_REQUEST",
          "message": "Payment not found or not yet captured",
          "retriable": false
        }
      ],
      "request_id": "<request-id>"
    }
    ```
  </Accordion>

  <Accordion title="The payment state does not contain the card brand required for the balance check">
    **HTTP 400 Bad Request** · `INVALID_REQUEST` · Retriable: **No**

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

  <Accordion title="The payment is not in a refundable state">
    **HTTP 409 Conflict** · `INVALID_STATE` · Retriable: **No**

    ```json theme={null}
    {
      "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>"
    }
    ```
  </Accordion>

  <Accordion title="No amount remains available for refund">
    **HTTP 400 Bad Request** · `INVALID_REQUEST` · Retriable: **No**

    ```json theme={null}
    {
      "errors": [
        {
          "category": "VALIDATION",
          "code": "INVALID_REQUEST",
          "message": "No remaining amount available for refund",
          "retriable": false
        }
      ],
      "request_id": "<request-id>"
    }
    ```
  </Accordion>

  <Accordion title="The refund amount is zero or negative">
    **HTTP 400 Bad Request** · `INVALID_REQUEST` · Retriable: **No**

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

  <Accordion title="The refund amount exceeds the remaining refundable amount">
    **HTTP 400 Bad Request** · `INVALID_REQUEST` · Retriable: **No**

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

  <Accordion title="lite cannot start the payment operation">
    **HTTP 503 Service Unavailable** · `WORKFLOW_SUBMISSION_FAILED` · Retriable: **Yes**

    ```json theme={null}
    {
      "errors": [
        {
          "category": "CONNECTION",
          "code": "WORKFLOW_SUBMISSION_FAILED",
          "message": "Payment orchestrator is temporarily unavailable",
          "retriable": true
        }
      ],
      "request_id": "<request-id>"
    }
    ```
  </Accordion>
</AccordionGroup>

#### 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.

<AccordionGroup>
  <Accordion title="Authorization extension is disabled in the current environment">
    **HTTP 500 Internal Server Error** · `INTERNAL_ERROR` · Retriable: **Yes**

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

  <Accordion title="The payment is not found">
    **HTTP 404 Not Found** · `PAYMENT_NOT_FOUND` · Retriable: **No**

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

  <Accordion title="The payment is not in `AUTHORIZED` status">
    **HTTP 409 Conflict** · `INVALID_STATE` · Retriable: **No**

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

  <Accordion title="lite cannot start the payment operation">
    **HTTP 503 Service Unavailable** · `WORKFLOW_SUBMISSION_FAILED` · Retriable: **Yes**

    ```json theme={null}
    {
      "errors": [
        {
          "category": "CONNECTION",
          "code": "WORKFLOW_SUBMISSION_FAILED",
          "message": "Payment orchestrator is temporarily unavailable",
          "retriable": true
        }
      ],
      "request_id": "<request-id>"
    }
    ```
  </Accordion>
</AccordionGroup>

#### 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.

<AccordionGroup>
  <Accordion title="The payment or order is not found">
    **HTTP 404 Not Found** · `PAYMENT_NOT_FOUND` · Retriable: **No**

    ```json theme={null}
    {
      "errors": [
        {
          "category": "VALIDATION",
          "code": "PAYMENT_NOT_FOUND",
          "message": "The payment was not found. Verify the payment ID.",
          "retriable": false
        }
      ],
      "request_id": "<request-id>"
    }
    ```
  </Accordion>
</AccordionGroup>

#### 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`.

<AccordionGroup>
  <Accordion title="`page` or `pageSize` is not a positive integer">
    **HTTP 400 Bad Request** · `INVALID_FIELD_VALUE` · Retriable: **No**

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

  <Accordion title="`pageSize` is greater than 100">
    **HTTP 400 Bad Request** · `INVALID_FIELD_VALUE` · Retriable: **No**

    ```json theme={null}
    {
      "errors": [
        {
          "category": "VALIDATION",
          "code": "INVALID_FIELD_VALUE",
          "message": "pageSize must not exceed 100",
          "retriable": false
        }
      ],
      "request_id": "<request-id>"
    }
    ```
  </Accordion>

  <Accordion title="`status` is unsupported">
    **HTTP 400 Bad Request** · `INVALID_FIELD_VALUE` · Retriable: **No**

    ```json theme={null}
    {
      "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>"
    }
    ```
  </Accordion>

  <Accordion title="`paymentMethod` is unsupported">
    **HTTP 400 Bad Request** · `INVALID_FIELD_VALUE` · Retriable: **No**

    ```json theme={null}
    {
      "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>"
    }
    ```
  </Accordion>

  <Accordion title="`fromDate` is invalid">
    **HTTP 400 Bad Request** · `INVALID_FIELD_VALUE` · Retriable: **No**

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

  <Accordion title="`toDate` is invalid">
    **HTTP 400 Bad Request** · `INVALID_FIELD_VALUE` · Retriable: **No**

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

  <Accordion title="`fromDate` is later than `toDate`">
    **HTTP 400 Bad Request** · `INVALID_FIELD_VALUE` · Retriable: **No**

    ```json theme={null}
    {
      "errors": [
        {
          "category": "VALIDATION",
          "code": "INVALID_FIELD_VALUE",
          "message": "fromDate must be earlier than toDate",
          "retriable": false
        }
      ],
      "request_id": "<request-id>"
    }
    ```
  </Accordion>
</AccordionGroup>

### 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`

<AccordionGroup>
  <AccordionGroup>
    <Accordion title="The merchant ID is missing">
      **HTTP 400 Bad Request** · `INVALID_REQUEST` · Retriable: **No**

      ```json theme={null}
      {
        "errors": [
          {
            "category": "VALIDATION",
            "code": "INVALID_REQUEST",
            "message": "Merchant ID is required",
            "retriable": false
          }
        ],
        "request_id": "<request-id>"
      }
      ```
    </Accordion>

    <Accordion title="The terminal ID is missing for a merchant-initiated payment">
      **HTTP 400 Bad Request** · `INVALID_REQUEST` · Retriable: **No**

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

    <Accordion title="The amount or currency is invalid">
      **HTTP 400 Bad Request** · `INVALID_REQUEST` · Retriable: **No**

      ```json theme={null}
      {
        "errors": [
          {
            "category": "VALIDATION",
            "code": "INVALID_REQUEST",
            "message": "Invalid payment amount or currency",
            "retriable": false
          }
        ],
        "request_id": "<request-id>"
      }
      ```
    </Accordion>
  </AccordionGroup>

  <Accordion title="lite cannot start the payment operation">
    **HTTP 503 Service Unavailable** · `WORKFLOW_SUBMISSION_FAILED` · Retriable: **Yes**

    ```json theme={null}
    {
      "errors": [
        {
          "category": "CONNECTION",
          "code": "WORKFLOW_SUBMISSION_FAILED",
          "message": "Payment orchestrator is temporarily unavailable",
          "retriable": true
        }
      ],
      "request_id": "<request-id>"
    }
    ```
  </Accordion>
</AccordionGroup>

#### Update a POS payment

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

<AccordionGroup>
  <Accordion title="`provider` is missing">
    **HTTP 400 Bad Request** · `INVALID_REQUEST` · Retriable: **No**

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

  <Accordion title="`raw_receipt` is missing when `error` is not provided">
    **HTTP 400 Bad Request** · `INVALID_REQUEST` · Retriable: **No**

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

  <Accordion title="The provider is unsupported">
    **HTTP 400 Bad Request** · `INVALID_REQUEST` · Retriable: **No**

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

  <Accordion title="The receipt does not match the expected schema">
    **HTTP 400 Bad Request** · `INVALID_REQUEST` · Retriable: **No**

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

  <AccordionGroup>
    <Accordion title="The merchant ID is missing">
      **HTTP 400 Bad Request** · `INVALID_REQUEST` · Retriable: **No**

      ```json theme={null}
      {
        "errors": [
          {
            "category": "VALIDATION",
            "code": "INVALID_REQUEST",
            "message": "Merchant ID is required",
            "retriable": false
          }
        ],
        "request_id": "<request-id>"
      }
      ```
    </Accordion>

    <Accordion title="The terminal ID is missing for a merchant-initiated payment">
      **HTTP 400 Bad Request** · `INVALID_REQUEST` · Retriable: **No**

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

    <Accordion title="The amount or currency is invalid">
      **HTTP 400 Bad Request** · `INVALID_REQUEST` · Retriable: **No**

      ```json theme={null}
      {
        "errors": [
          {
            "category": "VALIDATION",
            "code": "INVALID_REQUEST",
            "message": "Invalid payment amount or currency",
            "retriable": false
          }
        ],
        "request_id": "<request-id>"
      }
      ```
    </Accordion>
  </AccordionGroup>

  <Accordion title="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.
  </Accordion>

  <Accordion title="lite cannot process the payment update">
    **HTTP 503 Service Unavailable** · `WORKFLOW_SUBMISSION_FAILED` · Retriable: **Yes**

    ```json theme={null}
    {
      "errors": [
        {
          "category": "CONNECTION",
          "code": "WORKFLOW_SUBMISSION_FAILED",
          "message": "Payment orchestrator is temporarily unavailable",
          "retriable": true
        }
      ],
      "request_id": "<request-id>"
    }
    ```
  </Accordion>
</AccordionGroup>

#### Retrieve the latest POS payment

`GET /api/v1/pos/payments/latest`

<AccordionGroup>
  <Accordion title="No payment exists for the terminal">
    **HTTP 404 Not Found** · `PAYMENT_NOT_FOUND` · Retriable: **No**

    ```json theme={null}
    {
      "errors": [
        {
          "category": "VALIDATION",
          "code": "PAYMENT_NOT_FOUND",
          "message": "No POS payment found for terminal",
          "retriable": false
        }
      ],
      "request_id": "<request-id>"
    }
    ```
  </Accordion>
</AccordionGroup>

`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.

<AccordionGroup>
  <Accordion title="lite cannot start 3D Secure authentication">
    **HTTP 500 Internal Server Error** · `INTERNAL_ERROR` · Retriable: **Yes**

    ```json theme={null}
    {
      "errors": [
        {
          "category": "SYSTEM",
          "code": "INTERNAL_ERROR",
          "message": "Failed to process 3DS authentication",
          "retriable": true
        }
      ],
      "request_id": "<request-id>"
    }
    ```
  </Accordion>

  <Accordion title="The 3D Secure record is not found">
    **HTTP 404 Not Found** · `ENTITY_NOT_FOUND` · Retriable: **No**

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

  <Accordion title="The 3D Secure record is not found during confirmation">
    **HTTP 404 Not Found** · `ENTITY_NOT_FOUND` · Retriable: **No**

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

  <Accordion title="The authentication is not in challenge state">
    **HTTP 409 Conflict** · `INVALID_STATE` · Retriable: **No**

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

  <Accordion title="lite cannot retrieve the 3D Secure status">
    **HTTP 500 Internal Server Error** · `INTERNAL_ERROR` · Retriable: **Yes**

    ```json theme={null}
    {
      "errors": [
        {
          "category": "SYSTEM",
          "code": "INTERNAL_ERROR",
          "message": "Failed to get 3DS status",
          "retriable": true
        }
      ],
      "request_id": "<request-id>"
    }
    ```
  </Accordion>

  <Accordion title="lite cannot confirm the 3D Secure challenge">
    **HTTP 500 Internal Server Error** · `INTERNAL_ERROR` · Retriable: **Yes**

    ```json theme={null}
    {
      "errors": [
        {
          "category": "SYSTEM",
          "code": "INTERNAL_ERROR",
          "message": "Failed to confirm 3DS",
          "retriable": true
        }
      ],
      "request_id": "<request-id>"
    }
    ```
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

#### Browser challenge

`/v1/threeds/redirect`

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

##### `GET /challenge`

<AccordionGroup>
  <Accordion title="The redirect token is invalid or expired">
    **HTTP 401 Unauthorized** · `UNAUTHORIZED` · Retriable: **No**

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

  <Accordion title="The 3D Secure record is not found">
    **HTTP 404 Not Found** · `ENTITY_NOT_FOUND` · Retriable: **No**

    ```json theme={null}
    {
      "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>"
    }
    ```
  </Accordion>

  <Accordion title="The 3D Secure request is invalid">
    **HTTP 400 Bad Request** · `INVALID_REQUEST` · Retriable: **No**

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

  <Accordion title="The authentication is not in the required state, or challenge data is missing">
    **HTTP 409 Conflict** · `INVALID_STATE` · Retriable: **No**

    ```json theme={null}
    {
      "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>"
    }
    ```
  </Accordion>
</AccordionGroup>

##### `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.

<AccordionGroup>
  <Accordion title="`POST /`: `mode` and `max_uses` are inconsistent">
    **HTTP 400 Bad Request** · `INVALID_REQUEST` · Retriable: **No**

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

  <Accordion title="`PATCH /:id`: the requested status transition is not allowed">
    **HTTP 400 Bad Request** · `INVALID_REQUEST` · Retriable: **No**

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

  <Accordion title="`PATCH /:id`: the link has already been used">
    **HTTP 400 Bad Request** · `INVALID_REQUEST` · Retriable: **No**

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

  <Accordion title="`POST /`: `merchant_reference_id` already exists">
    **HTTP 409 Conflict** · `DUPLICATE_REQUEST` · Retriable: **No**

    ```json theme={null}
    {
      "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>"
    }
    ```
  </Accordion>

  <Accordion title="`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**

    ```json theme={null}
    {
      "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>"
    }
    ```
  </Accordion>
</AccordionGroup>

#### 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:

```text theme={null}
?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:

<AccordionGroup>
  <Accordion title="The link does not exist">
    **HTTP 404 Not Found** · `ENTITY_NOT_FOUND` · Retriable: **No**

    ```json theme={null}
    {
      "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>"
    }
    ```
  </Accordion>

  <Accordion title="A single-use link currently has no available slot">
    **HTTP 409 Conflict** · `DUPLICATE_REQUEST` · Retriable: **No**

    ```json theme={null}
    {
      "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>"
    }
    ```
  </Accordion>

  <Accordion title="lite cannot create the checkout session">
    **HTTP 502 Bad Gateway** · `PROVIDER_CONNECTION_ERROR` · Retriable: **Yes**

    ```json theme={null}
    {
      "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>"
    }
    ```
  </Accordion>

  <Accordion title="The link is expired, paid, disabled, or has reached its usage limit">
    **HTTP 500 Internal Server Error** · `INTERNAL_ERROR` · Retriable: **Yes**

    ```json theme={null}
    {
      "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>"
    }
    ```
  </Accordion>

  <Accordion title="The consumption record cannot be created">
    **HTTP 500 Internal Server Error** · `INTERNAL_ERROR` · Retriable: **Yes**

    ```json theme={null}
    {
      "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>"
    }
    ```
  </Accordion>
</AccordionGroup>

### 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`.

<AccordionGroup>
  <Accordion title="Field validation fails">
    **HTTP 400 Bad Request** · `MISSING_REQUIRED_FIELD` or `INVALID_FIELD_VALUE` · Retriable: **No**

    ```json theme={null}
    {
      "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>"
    }
    ```
  </Accordion>
</AccordionGroup>

| 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:

<AccordionGroup>
  <Accordion title="The payment method is unsupported">
    **HTTP 400 Bad Request** · `INVALID_REQUEST` · Retriable: **No**

    ```json theme={null}
    {
      "errors": [
        {
          "category": "VALIDATION",
          "code": "INVALID_REQUEST",
          "message": "Unsupported payment method",
          "retriable": false
        }
      ],
      "request_id": "<request-id>"
    }
    ```
  </Accordion>

  <Accordion title="Apple Pay `data` is not valid JSON">
    **HTTP 400 Bad Request** · `INVALID_REQUEST` · Retriable: **No**

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

  <Accordion title="The payment token cannot be decrypted">
    **HTTP 400 Bad Request** · `INVALID_REQUEST` · Retriable: **No**

    ```json theme={null}
    {
      "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>"
    }
    ```
  </Accordion>

  <Accordion title="lite cannot process the Apple Pay data">
    **HTTP 400 Bad Request** · `INVALID_REQUEST` · Retriable: **No**

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

  <Accordion title="Card details are missing">
    **HTTP 400 Bad Request** · `INVALID_REQUEST` · Retriable: **No**

    ```json theme={null}
    {
      "errors": [
        {
          "category": "VALIDATION",
          "code": "INVALID_REQUEST",
          "message": "PAN data is required",
          "retriable": false
        }
      ],
      "request_id": "<request-id>"
    }
    ```
  </Accordion>

  <Accordion title="lite cannot tokenize or save the instrument">
    **HTTP 500 Internal Server Error** · `INTERNAL_ERROR` · Retriable: **Yes**

    ```json theme={null}
    {
      "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>"
    }
    ```
  </Accordion>

  <Accordion title="lite cannot create the instrument">
    **HTTP 500 Internal Server Error** · `INTERNAL_ERROR` · Retriable: **Yes**

    ```json theme={null}
    {
      "errors": [
        {
          "category": "SYSTEM",
          "code": "INTERNAL_ERROR",
          "message": "Failed to CreateInstrument",
          "retriable": true
        }
      ],
      "request_id": "<request-id>"
    }
    ```
  </Accordion>
</AccordionGroup>

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`

<AccordionGroup>
  <Accordion title="The lookup input fails validation">
    **Response:** `400 MISSING_REQUIRED_FIELD` or `400 INVALID_FIELD_VALUE`\
    **Retriable:** No

    Field validation can return one error per invalid field:

    ```json theme={null}
    {
      "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>"
    }
    ```
  </Accordion>

  <Accordion title="lite cannot list instruments">
    **HTTP 500 Internal Server Error** · `INTERNAL_ERROR` · Retriable: **Yes**

    ```json theme={null}
    {
      "errors": [
        {
          "category": "SYSTEM",
          "code": "INTERNAL_ERROR",
          "message": "Failed to LookupInstruments",
          "retriable": true
        }
      ],
      "request_id": "<request-id>"
    }
    ```
  </Accordion>
</AccordionGroup>

#### Retrieve an instrument

`GET /api/v1/instruments/:id`

<AccordionGroup>
  <Accordion title="The instrument is not found">
    **HTTP 404 Not Found** · `ENTITY_NOT_FOUND` · Retriable: **No**

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

  <Accordion title="The instrument belongs to another merchant">
    **HTTP 403 Forbidden** · `ENTITY_ACCESS_DENIED` · Retriable: **No**

    ```json theme={null}
    {
      "errors": [
        {
          "category": "SETUP",
          "code": "ENTITY_ACCESS_DENIED",
          "message": "Access denied to this instrument.",
          "retriable": false
        }
      ],
      "request_id": "<request-id>"
    }
    ```
  </Accordion>

  <Accordion title="lite cannot retrieve the instrument">
    **HTTP 500 Internal Server Error** · `INTERNAL_ERROR` · Retriable: **Yes**

    ```json theme={null}
    {
      "errors": [
        {
          "category": "SYSTEM",
          "code": "INTERNAL_ERROR",
          "message": "Failed to GetInstrumentById",
          "retriable": true
        }
      ],
      "request_id": "<request-id>"
    }
    ```
  </Accordion>
</AccordionGroup>

#### Update an instrument

`PUT /api/v1/instruments/action`

<AccordionGroup>
  <Accordion title="`instrument_id` or `action_type` fails validation">
    **Response:** `400 MISSING_REQUIRED_FIELD` or `400 INVALID_FIELD_VALUE`\
    **Retriable:** No

    Field validation can return one error per invalid field:

    ```json theme={null}
    {
      "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>"
    }
    ```
  </Accordion>

  <Accordion title="The instrument is not found">
    **HTTP 404 Not Found** · `ENTITY_NOT_FOUND` · Retriable: **No**

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

  <Accordion title="The requested action is not publicly supported">
    **HTTP 400 Bad Request** · `INVALID_REQUEST` · Retriable: **No**

    ```json theme={null}
    {
      "errors": [
        {
          "category": "VALIDATION",
          "code": "INVALID_REQUEST",
          "message": "<Action description> is not currently supported",
          "retriable": false
        }
      ],
      "request_id": "<request-id>"
    }
    ```
  </Accordion>

  <Accordion title="The action is not allowed in the instrument's current state">
    **HTTP 409 Conflict** · `INVALID_STATE` · Retriable: **No**

    ```json theme={null}
    {
      "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>"
    }
    ```
  </Accordion>

  <Accordion title="lite cannot update the instrument">
    **HTTP 500 Internal Server Error** · `INTERNAL_ERROR` · Retriable: **Yes**

    ```json theme={null}
    {
      "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>"
    }
    ```
  </Accordion>
</AccordionGroup>

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.

<AccordionGroup>
  <Accordion title="The provider name, CSR, session, or channel data is invalid">
    **HTTP 400 Bad Request** · `INVALID_REQUEST` · Retriable: **No**

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

  <Accordion title="Provider-session authentication fails">
    **HTTP 401 Unauthorized** · `UNAUTHORIZED` · Retriable: **No**

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

  <Accordion title="The operation is forbidden">
    **HTTP 403 Forbidden** · `FORBIDDEN` · Retriable: **No**

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

  <Accordion title="A mapping, credential, or provider is not found">
    **HTTP 404 Not Found** · `ENTITY_NOT_FOUND` · Retriable: **No**

    ```json theme={null}
    {
      "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>"
    }
    ```
  </Accordion>

  <Accordion title="The mapping already exists">
    **HTTP 409 Conflict** · `DUPLICATE_REQUEST` · Retriable: **No**

    ```json theme={null}
    {
      "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>"
    }
    ```
  </Accordion>

  <Accordion title="An upstream device-payment request fails">
    **HTTP 502 Bad Gateway** · `PROVIDER_CONNECTION_ERROR` · Retriable: **Yes**

    ```json theme={null}
    {
      "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>"
    }
    ```
  </Accordion>

  <Accordion title="The payment provider is unavailable">
    **HTTP 503 Service Unavailable** · `PROVIDER_UNAVAILABLE` · Retriable: **Yes**

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

  <Accordion title="The payment provider times out">
    **HTTP 504 Gateway Timeout** · `GATEWAY_TIMEOUT` · Retriable: **Yes**

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

  <Accordion title="An internal error occurs">
    **HTTP 500 Internal Server Error** · `INTERNAL_ERROR` · Retriable: **Yes**

    ```json theme={null}
    {
      "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>"
    }
    ```
  </Accordion>
</AccordionGroup>