Errors return JSON in the following shape. Treat the HTTP status and error.code as the contract; display messages can change.
{
"error": {
"code": "invalid_request",
"message": "Items must reconcile to the order amount."
}
}- HTTP 400
invalid_request · invalid_idempotency_key · invalid_return_url · unregistered_return_url - Correct the fields, idempotency header or registered return URL before retrying.
- HTTP 401
unauthorized - Check the complete key, its matching API base URL, expiry and revocation status.
- HTTP 403
forbidden - Check orders_read / orders_write permission and any configured merchant IP restrictions.
- HTTP 404
not_found - Check the resource ID and the merchant account tied to your key. Inaccessible resources return the same error as missing ones.
- HTTP 409
idempotency_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 / 431
body_too_large · headers_too_large - Reduce payload size. Request bodies are limited to 64 KiB; combined header values to 16 KiB.
- HTTP 429
rate_limited - Honor Retry-After (currently 60 seconds), then retry with backoff. Reuse the original idempotency key when retrying order or session creation.
- HTTP 503
unavailable · 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.