Rate limits

Quotient limits paid API traffic at the gateway before it debits credits, settles an x402 payment, or starts upstream work. Read the relevant operation's x-rate-limit before scheduling calls and use the most conservative shared policy across a multi-operation workflow.

Policies with the same caller identity share their counters. Runtime rate-limit headers are authoritative for that caller.

How callers are counted

• API keys are grouped by customer, not key text. Rotating keys on one account does not add capacity.
• x402 calls use the verified payer address when available. If no payer identity can be derived, the normalized client IP is the fallback.
• The ip_abuse_guard policy is secondary anti-key-spray protection, not additional quota, and may tighten during active abuse.
• The unsigned request used to obtain a 402 payment challenge counts only against the loose IP guard. The signed retry also counts against the customer/payer quota.

Minute counters reset at the next minute boundary. Daily counters reset at 00:00 UTC. The shared counters and concurrency lease live in durable gateway storage, so ordinary deploys or multiple gateway replicas do not multiply the published quota.

Read the response headers

Admitted responses include:

RateLimit-Policy: "<scope>-second";q=<quota>;w=1, "<scope>-minute";q=<quota>;w=60
RateLimit: "<scope>-second";r=<remaining>;t=<reset-seconds>, ...
X-Quotient-Max-Concurrent: <max-concurrent>

q is the quota, w its window in seconds, r the remaining requests, and t the seconds to reset. The exact RateLimit values on the response are authoritative for that caller.

Handle a 429

A rejected request returns 429 rate_limited and a whole-second Retry-After header:

HTTP/1.1 429 Too Many Requests
Retry-After: <whole-seconds>
RateLimit-Policy: <current-policy>
Content-Type: application/json

{
  "error": "rate_limited",
  "message": "The standard per-minute limit was reached.",
  "retry_after": <whole-seconds>,
  "limit_scope": "<scope>"
}

Stop any fan-out, wait for Retry-After plus a small amount of jitter, then retry once and serially. A 429 is rejected before billing or provider work, so it does not consume credits and does not settle an x402 payment. An admitted request still counts toward quota if it later lacks credits or its upstream fails. Quotient's bundled shell and JavaScript skill clients derive their safe start interval from the reviewed OpenAPI contract for multi-read workflows.

Safe polling pattern

For /latest, poll no faster than once per minute for ordinary monitoring. Each call returns its whole requested window without a cursor. For multi-endpoint agent work, queue calls and maintain at least the interval published by the strictest selected operation rather than using unbounded Promise.all or parallel shell jobs.

Settled x402 payment identifiers are request-bound. An exact retry returns the cached original response; changing the payment proof, method, URL, query, or body under the same identifier returns 409 payment_replay_mismatch instead of executing another read.