Read the quota response headers
API responses that pass an enforced quota include RateLimit-Policy and RateLimit Structured Field lists. These use draft-ietf-httpapi-ratelimit-headers-11, an IETF Internet-Draft rather than a published RFC. The API and public web proxies preserve these headers. Quota responses cannot be cached. Requests that do not pass an enforced quota do not advertise an invented allowance.
RateLimit-Policy: "quota-1";q=20;w=60
RateLimit: "quota-1";r=19;t=30Throttle before reaching the limit
In RateLimit-Policy, q is the request allowance and w is the window in seconds. In RateLimit, r is the remaining allowance after reserving the current request and t is the seconds until reset. More than one policy can apply to a response. Policy names are local to that response, and concurrent requests can consume the remaining allowance. Authentication quotas that count failures can refund a successful request after responding.
Publishable checkout creation is limited to 20 requests per minute per key and client IP. Public invoice and payment-link views allow 120 requests per minute per client IP; checkout submissions allow 10. Other endpoints have their own policies. Secret-key operations do not advertise a quota unless a limiter actually applies. Read the response headers instead of assuming one global rate.
Handle HTTP 429
A quota rejection returns HTTP 429 with Retry-After in seconds. Wait at least that interval before sending another request, and reduce concurrent traffic. The error body retains success: false, error.code, error.message, and meta.requestId. Only retry a mutation when its idempotency contract allows it; reuse an idempotency key only for the same operation and payload.
HTTP/1.1 429 Too Many Requests
RateLimit-Policy: "quota-1";q=20;w=60
RateLimit: "quota-1";r=0;t=30
Retry-After: 30