Rate limits

• The budget belongs to the key (an app install token, an agent key, or the account for a user JWT). It is shared by every Agent Gateway route, /api/v1/agent/v1/* and /api/v1/agent/2026-08/*, whichever engine serves the route.
• The window is fixed: it starts with your first request and resets 60 seconds later.
• Every call counts as one request, however much it returns or changes. Batch endpoints are the way to do more per request: GET /products?include=variants&limit=250 reads 250 products with their variants, and POST /products/variants/bulk_update writes 250 variants.
• The unauthenticated GET /health probe is exempt.

​

Headers

​

Pacing

• Keep a small reserve. When RateLimit-Remaining drops below about 10% of the limit, wait RateLimit-Reset seconds before the next non-urgent call.
• Spread background work (syncs, bulk jobs) over the window rather than bursting, so interactive calls from the same install still get through.
• Use the batch endpoints and fields= to cut the number of calls.
• On 429, wait exactly Retry-After seconds, then retry. Writes carry an Idempotency-Key, so retrying a 429’d write with the same key is safe.

import time, httpx

def call(client: httpx.Client, method: str, url: str, **kw) -> httpx.Response:
    while True:
        r = client.request(method, url, **kw)
        if r.status_code != 429:
            remaining = int(r.headers.get("RateLimit-Remaining", "1"))
            if remaining == 0:
                time.sleep(int(r.headers.get("RateLimit-Reset", "1")))
            return r
        time.sleep(int(r.headers.get("Retry-After", "1")))