DOCUMENTATION API v2

Errors & limits

Errors return JSON in the following shape. Treat the HTTP status and error.code as the contract; display messages can change.

Error response · JSON
{
  "error": {
    "code": "invalid_request",
    "message": "Items must reconcile to the order amount."
  }
}
HTTP 400invalid_request · invalid_idempotency_key · invalid_return_url · unregistered_return_url
Correct the fields, idempotency header or registered return URL before retrying.
HTTP 401unauthorized
Check the complete key, its matching API base URL, expiry and revocation status.
HTTP 403forbidden
Check orders_read / orders_write permission and any configured merchant IP restrictions.
HTTP 404not_found
Check the resource ID and the merchant account tied to your key. Inaccessible resources return the same error as missing ones.
HTTP 409idempotency_conflict · order_not_pending · mandate_automatic · mandate_not_active · mandate_limit_exceeded
For a reference or key conflict, retry the original request or use a new reference for a different order. An order_not_pending response means the order can no longer be cancelled; retrieve its current state. For mandate_automatic, mandate_not_active or mandate_limit_exceeded, the subscription is charged on its schedule, has ended or is not active yet, or the charge is above its per-charge or per-period limit; retrieve the subscription before charging again.
HTTP 413 / 431body_too_large · headers_too_large
Reduce payload size. Request bodies are limited to 64 KiB; combined header values to 16 KiB.
HTTP 429rate_limited
Honor Retry-After (currently 60 seconds), then retry with backoff. Reuse the original idempotency key when retrying order or session creation.
HTTP 503unavailable · fee_configuration_unavailable
Retry temporary failures with bounded exponential backoff and jitter. Reuse the original request and idempotency key for order or session creation.

Current merchant API limits are 120 requests per minute per IP and 300 authenticated requests per minute per merchant account. Respect Retry-After rather than polling rapidly.

All endpoints reject unexpected query parameters. Send JSON when creating an order or checkout session; order cancellation takes no request body. Monetary values are integer cents; timestamps are UTC. A replacement session requires milliseconds even though order creation also accepts timestamps without them.