Error Handling

Error responses use one envelope. It does not matter where the error came from — authentication, authorization, a business rule, a service — the fields are the same.

{
  "status": "failure",
  "code": "payment.card.declined",
  "message": "The card was declined",
  "statusCode": 409,
  "timestamp": "2026-08-17T10:32:23.816Z",
  "service": "api-gateway",
  "systemTime": 1786962743816,
  "requestId": "req_7f3d9c1a4b2e",
  "docsUrl": "https://docs.lunixi.com/getting-started/errors#INVALID_SIGNATURE"
}

Fields

Validation errors

When field validation fails, details breaks it down per field:

{
  "status": "failure",
  "code": "validation.error",
  "message": "Validation failed",
  "statusCode": 400,
  "requestId": "req_7f3d9c1a4b2e",
  "details": {
    "errors": [
      { "field": "amount", "errors": ["amount must be a minor-unit integer"] }
    ]
  }
}

Correlating with requestId

Every response — successful or not — carries an x-request-id header. The same value appears in the body's requestId field and in our microservice logs.

You can send your own id

If you send x-request-id (or x-correlation-id) on the request, it is respected and the same value comes back on the response. That lets you line up your tracing system with ours on a shared key.

Resolution order: x-request-id → x-correlation-id → the gateway generates one.

Choosing a language

The message field and the docsUrl link come back in the language you ask for.

x-lang: tr

Without x-lang, Accept-Language is used; without that, the installation's default language applies.

An unsupported language falls back to the default. For a code that is not in the dictionary the original message is shown — never a bare code.

HTTP status codes

Which errors to retry

Retry: 500 · 502 · 503 · 504 — with exponential backoff.

Do not retry: 400 · 401 · 403 · 409 · 422 — the outcome will not change while the request stays the same. Fix the request first.

Code dictionary

Each code below has its own heading or table row. When the response carries a docsUrl, the link lands directly on it.

VALIDATION_ERROR

One of the fields you sent is invalid. The reason is per field in details.errors[] — look at the field value there.

UNAUTHENTICATED

Not authenticated. Either there is no Authorization: Bearer … header, or the token is invalid or expired. A token typically lives 5 minutes — cache it and refresh based on expires_at. → Authentication

PERMISSION_DENIED

The token is valid but does not carry the scope this operation needs. Check the scopes granted to your key.

auth.permission.forbidden

The same condition as PERMISSION_DENIED, returned in granular-code form.

INVALID_SIGNATURE

The signature did not verify. The three most common causes:

1. You included the Digest: line in the canonical string on a bodyless request — it must be omitted. The canonical string for the token call is four lines.
2. Line order or header spelling differs.
3. The first argument to crypto.sign is not null — Ed25519 takes no hash algorithm.

→ The canonical string

NONCE_REPLAY

This X-Nonce has been used before. A nonce is single use; generate a fresh one per request (a UUID works).

IP_NOT_ALLOWED

The request came from an IP that is not on the allow-list for your key. If your server's egress IP changed (a new deploy, a NAT change), update the list.

MERCHANT_SUSPENDED

The account is suspended. This is not something a change to the request can fix — contact support.

AUTH_REFRESH_REUSED

A refresh token was used a second time and the session was terminated for security. This usually happens when two processes share the same token — centralise token refresh in one place.

PRODUCT_NOT_ENABLED

Your identity is valid and your permission is in place — but the endpoint you called belongs to a product you are not entitled to. Product is a separate axis from permission: holding the permission to perform an action does not mean the product is enabled on your account.

Two conditions must both hold; the panel shows you which one is missing:

If you have the subscription and still get this error, the second condition is almost always the missing one: an API key is a deliberate narrowing, and subscribing does not widen your existing keys automatically.

PRODUCT_ENTITLEMENT_UNAVAILABLE

Do not confuse this with PRODUCT_NOT_ENABLED. This code does not say "you lack the product"; it says "we cannot verify your product entitlement right now". The HTTP status is 503 and the condition is temporary.

The entitlement gate is fail-closed: we do not let a request through on an entitlement we could not verify. What you need is not a change to your account — it is a retry, with exponential backoff.

payment.amount.field_removed

Your payment request sent a removed amount field (price or paidPrice). The payment endpoints have a single amount field, amount: an integer in minor units, at least 1. The removed fields you sent are returned in details.fields, and any other field errors in details.errors[].

• amount is the basket total: the price of the goods and services the buyer pays for, excluding the installment fee. If you send basketItems, the items' price must add up to amount. The item price field is the line amount and stays as it is.
• You do not send the installment fee. For installments the system computes it from the binding installment quote and adds it to the charged amount.

→ Checkout Form · Card — 2D · Installments & BIN

payment.method.disabled

The payment method you chose is disabled in your business's form settings in the panel. A method disabled in the panel is disabled on every channel: it is not shown on the Checkout Form, it is not in the GET /payments/methods list, and it cannot be started with POST /payments/direct/payment. The HTTP status is 422; the payment is rejected before it starts and no money moves.

• To use the method, enable it under Payment Form Settings in the panel.
• Read which methods are enabled with GET /payments/methods.

→ Payment · Checkout Form — Payment

payment.method.unknown

The method code you sent is not recognized. The HTTP status is 400. Method codes are written in upper case (CARD, WALLET, MOBILE_BILLING …); the request is never turned into another method or into a card payment.

• In a POST /payments/direct/payment request, send a valid code in paymentMethod.
• In the GET /payments/methods?paymentMethod= filter, an unknown, lower-case, empty or repeated value gets this code. The response has details.field set to paymentMethod; every recognized code is in the details.allowed list.

→ Listing Methods · Payment

payment.provider.required

For this method the buyer chooses the provider (providerSelectionMode: BUYER) and more than one provider is connected to your account, but the request has no providerCode. The HTTP status is 400; the payment is rejected before it starts.

• The codes of the connected providers are in details.boundProviderCodes.
• Show the providers to the buyer and send the code of the one they choose as providerCode in the method block (e.g. wallet.providerCode).

→ Listing Methods › Provider selection · Pay with Wallet

payment.provider.none_eligible

For this method the platform chooses the provider (providerSelectionMode: PLATFORM), the request has no providerCode, and none of the providers connected to your account can take this payment. The HTTP status is 422. The payment is not started and nothing is charged.

Each provider's result is in details.candidates[]:

• If any result is UNAVAILABLE or NOT_CHECKED, you can retry the same request later.
• You can also choose the provider yourself with providerCode in the method block.
• If every result is INELIGIBLE, offer the buyer another method.

→ Mobile Billing › No provider is eligible · Listing Methods › Provider selection

payment.provider.disabled_in_form

The selected provider is turned off only for the form in the business's Form Settings. The HTTP status is 422; the payment is rejected before it starts and no money moves. This code is returned only on the Checkout Form path.

• The Checkout Form offers the buyer another provider or method shown in the form.
• To use the provider in the form, turn it on in the method's Payment options list on Payments → Form Settings in the panel.
• A provider turned off for the form stays in the GET /payments/methods list and can be used with POST /payments/direct/payment.

→ Checkout Form — Payment › Order and providers shown in the form

payment.method.selection_attempts_exhausted

The non-card method selection limit (3) for this payment has been reached. The HTTP status is 409; no selection is written, no provider is called and no money moves.

• The limit is per payment (order); new attempts on the same order share the same counter.
• The buyer can pay the same order by card.

→ Checkout Form — Payment › Provider choice

payment.checkout.order_locked

A split payment is in progress for the order; until it finishes, no single-card, non-card or wallet payment can be started for the same order. The HTTP status is 409; the payment record is not touched.

• Wait for the split payment to finish. If it fails, its time runs out or the buyer gives up, the order stays open and can be paid with another method.

→ Split Payments › Order lock

split_pay.checkout.order_not_open

Another payment has started for the order or the order is closed; a split payment cannot be started. The HTTP status is 409; no split payment is written and no card is charged. The reason is in details.reason:

→ Split Payments › Order lock

Split payment codes

Codes of the split payment endpoints (POST /payments/split, POST /payments/split/{splitPaymentId}/refund and the Checkout Form's split payment endpoints). The details are always in details.

Validation

The split payment is rejected before it starts; no part is charged. The HTTP status is 422. details.legIndex or details.index gives the position of the offending part (starting at 0).

Steps, the continuation link and the continuation page

details.reason for split_pay.step.not_allowed:

Refunds

→ Split Payments › Errors

Other common codes

These carry no docsUrl but come up often:

All fraud endpoint error codes, quota headers and retry rules: Fraud — Errors and Retries.

Privacy

Related

• Authentication — signed-request errors
• API Overview — the envelope and idempotency
• Webhooks — delivery failures are a separate mechanism