Errors and rate limits

Response envelope

Every response, success or error, uses the same envelope:

{
  "success": true,
  "uuid": "6b1f0c3e-2d4a-4f8b-9c1e-7a5d3b2f1e0c",
  "code": "SESSION_CREATED",
  "message": "...",
  "data": { "...": "..." },
  "errors": null
}

On an error, success is false, code is the error code, data is usually null, and errors lists problems by field (an empty list when there are none):

{
  "success": false,
  "uuid": "0e9d8c7b-...",
  "code": "VALIDATION_ERROR",
  "message": "One or more validation errors occurred.",
  "data": null,
  "errors": [
    { "field": "TotalAmount", "message": "Total amount must be greater than zero" },
    { "field": "Items[0].Quantity", "message": "Item quantity must be greater than zero." }
  ]
}

• Write your code against code and the HTTP status, not message. Messages are for people and can change.
• Field names in errors follow the request structure in PascalCase, for example ShippingAddress, Items[1].TotalAmount, MerchantUrl.Success.
• uuid identifies the request. Every response also carries X-Request-Id and X-Correlation-Id headers. If you send your own X-Correlation-Id (a UUID), it is echoed back and used as uuid, so you can match our logs to yours. Quote uuid when you contact support.

Responses without an envelope

A few responses have no JSON body. Don't assume one exists:

HTTP statuses

Error codes

Any endpoint

Creating orders (/pay/session/create, /pay/pos/create, /pay/qr/create)

Checkout links (/merchant/checkout-links)

Orders (/merchant/orders)

Webhook endpoints (/merchant/webhooks)

Plans widget (/widget/plans, publishable key)

Success codes

Successful responses also carry a code: SESSION_CREATED (sessions, POS, QR), LINK_CREATED, LINK_CANCELLED, WEBHOOK_CREATED, WEBHOOK_UPDATED, WEBHOOK_DELETED, SECRET_ROTATED, PING_QUEUED, DELIVERY_REPLAYED, OK (plan quotes) and SUCCESS (everything else). Check success and the HTTP status; don't rely on the exact success code.

Rate limits

• The window is a fixed one minute. Requests over the limit are refused at once, not queued.
• Each API key has its own budget, so one integration can't use up another's. A separate key per system also separates their limits.
• A refused request gets 429 with the code TOO_MANY_REQUESTS and a Retry-After header in seconds:

HTTP/1.1 429 Too Many Requests
Retry-After: 37
Content-Type: application/json

{ "success": false, "uuid": "...", "code": "TOO_MANY_REQUESTS", "message": "Too many requests. Try again in 37 second(s).", "data": null, "errors": [] }

On 429:

1. Stop sending requests with that key until Retry-After has passed.
2. Then retry with exponential backoff and random jitter if you are refused again.
3. When retrying a POST, reuse the same Idempotency-Key. A 429 is refused before the key is recorded, so the retry runs normally.

To stay under the limit, use webhooks instead of polling orders, and cache plan quotes per page.

Which errors to retry

• Retry with the same Idempotency-Key and the same body.
• Back off exponentially, for example min(2^attempt × 500 ms, 8 s) plus up to 250 ms of random jitter, and honour Retry-After on 429. Give up after a few attempts.
• A 500 on a write may or may not have done its work. Before you retry a create, look the order up with GET /api/v1/merchant/orders/by-reference/{orderReferenceId}. Before you retry a refund or fulfilment, read the order and compare refundedAmount or fulfilledAmount. If you retry, use the same Idempotency-Key; your orderReferenceId also protects you from a second order.
• The server SDKs follow these rules for you: they retry network errors, 429, 502, 503, 504 and 409 REQUEST_IN_PROGRESS, and never retry other 4xx or 500.

Troubleshooting

Related