Errors and request IDs

Error layers

A transport error means the connection did not complete; it does not prove that the financial operation was not executed. An HTTP error means the server returned a response, while the JSON body provides a code, message, and validation details. Keep these layers separate in your client library.

Important statuses

Use 400 for a malformed request or missing business selector, 401 for invalid credentials, 403 for a denied scope, 404 for a missing resource, 409 for idempotency or state-transition conflict, 422 for validation or control decisions, and 429 for rate limiting. Do not collapse all statuses into one message or retry every failure.

Request ID

Generate a unique X-Request-ID for each transport attempt and keep it separate from the business intent or idempotency key. The request ID correlates your log with LuxPay observability, while the idempotency key joins multiple attempts to one financial operation. Never embed personal data or secrets in the identifier.

User messaging

Show a safe, understandable message to the user and record the technical code and request ID internally. Do not expose stack traces or database details. When contacting support, provide timestamp, environment, operation ID, request ID, resource identifier, and HTTP status—never the token or password.

Error envelopes

Because the current API contains two historical response conventions, a failure may use success: false or status: false. A client should classify by HTTP status first, then read the available fields instead of assuming one envelope for every route.