Rate limits

Limits are counted per key with a token bucket. The defaults come from your plan. Typical defaults are 100 requests per second for secret keys and 20 for publishable keys.

Unauthenticated routes, such as login, OTP and guest checkout, are limited per IP address. A few endpoints have stricter limits of their own: sending an OTP, minting a token and syncing check-ins.

Headers

Header	Meaning
RateLimit-Limit	Requests allowed in the window
RateLimit-Remaining	Requests left in the window
RateLimit-Reset	Seconds until the window resets
Retry-After	On 429 only: seconds to wait before you retry

When you hit a limit

You get 429 with an error of type rate_limit_error and a Retry-After header. Wait for Retry-After, then retry. If you must retry several times, use exponential backoff with jitter, and send an Idempotency-Key so a retry cannot repeat the action.

Stay under the limit

• Watch RateLimit-Remaining and slow down before it reaches zero.
• Use limit=100 on lists, and expand[], instead of many small calls.
• Use webhooks instead of polling.