Errors and retries
Distinguish validation errors, authentication refusals, conflicts, and uncertain outcomes.
Response formats
Validation errors include a machine-readable code:
{ "statusCode": 400, "code": "INVALID_REQUEST", "message": "Request validation failed" }Mapped domain errors use their code as the message:
{ "statusCode": 409, "code": "ORDER_ID_ALREADY_EXISTS", "message": "ORDER_ID_ALREADY_EXISTS" }Authentication and path-validation errors can use the standard Nest format instead:
{ "statusCode": 401, "message": "Invalid merchant credentials", "error": "Unauthorized" }Do not assume every error has a code property. Handle HTTP status first, then inspect the available safe code or message.
Common outcomes
| HTTP status | Examples | Action |
|---|---|---|
400 | INVALID_REQUEST, malformed fields | Correct the request. |
401 | Missing or invalid merchant credentials | Check merchant status, ID, key, and serialization. |
403 | API_SOURCE_NOT_ALLOWED | Check the allowed source addresses. |
404 | ITEM_NOT_FOUND, INVOICE_NOT_FOUND | Check the saved identifier and ownership. |
409 | ORDER_ID_ALREADY_EXISTS, ITEM_ARCHIVED, expiry or method conflicts | Resolve the business conflict before retrying. |
422 | Unsupported currency, token, network, or payment method | Use an eligible combination. |
502 | Invalid upstream payment state or upstream failure | Reconcile the invoice and contact support if persistent. |
503 | Dependency or rate unavailable | Retry later with the same operation identity. |
504 | UPSTREAM_TIMEOUT | The operation may have committed; reconcile or retry idempotently. |
Safe invoice retries
Supply order_id on the first create request. Reuse it with identical business fields after a timeout or temporary failure. Changing fields for that existing order returns a conflict. Without an order ID, separate calls can create separate invoices.
Do not regenerate an explicit expiry, order ID, or other request field on every retry. A changed request is a different set of conditions. The server normalizes insignificant decimal zeroes and object-key order for invoice deduplication, but API authentication still follows its own exact serialization rules.
Limits and support
Request-field limits are listed on the endpoint pages. Production rate limits and ingress policies depend on deployment; this documentation does not promise an unverified requests-per-second quota.
For support, include a request time in UTC, the endpoint, HTTP status, and invoice or order reference. Never include secrets, signatures, or session cookies.