Rate limits

Requests are rate limited per API key using a fixed one-minute window.

The limit#

• Default: 2,000 requests per minute per API key (configurable per deployment via RATE_LIMIT_PER_MINUTE).
• The window is keyed by API key and the current minute. All endpoints called with that key share the window.
• The limiter is designed to never block the decision path on its own infrastructure: if its backing store is unreachable, requests pass through unlimited rather than failing checkout.

When you exceed it#

HTTP/1.1 429 Too Many Requests

{ "error": "rate_limited", "limit_per_minute": 2000 }

There is no Retry-After header today. Because the window is a fixed minute, backing off to the start of the next minute is always sufficient.

Handling 429 in the payment path#

A checkout request should never sit in a retry loop waiting for a rate window. Treat 429 on POST /v1/decision like a timeout: take your merchant-defined fallback path immediately, and alert, because sustained 429s mean your traffic outgrew the configured limit.

For non-latency-critical calls (POST /v1/outcomes, GET endpoints), queue and retry after a short backoff. Outcome reporting is idempotent, so delayed redelivery is safe.

Staying under the limit#

• Use separate keys per service. Each key gets its own window, and a burst from one service does not starve another.
• Do not poll GET /v1/provider-health or the decision log in a tight loop; snapshots update on background cadence, so polling faster than every few seconds buys nothing.
• If you expect sustained volume near the default limit, raise RATE_LIMIT_PER_MINUTE in your deployment or ask your operator to.