Rate limits

Every request is rate-limited per API key to keep the service responsive for everyone.

How it works#

Each key has a token bucket that refills continuously. A request consumes one token; when the bucket is empty the API responds with 429 and a Retry-After header telling you how long to wait.

Response headers#

Every response carries your current limit state:

Field	Type	Description
`x-ratelimit-limit`	integer	Requests allowed per minute for this key.
`x-ratelimit-remaining`	integer	Tokens left in the current window.
`retry-after`	integer	On a 429, seconds to wait before retrying.

Handling 429#

Back off and retry after the Retry-After delay:

python

import time, httpx

def with_retry(do_request, max_tries=5):
    for attempt in range(max_tries):
        r = do_request()
        if r.status_code != 429:
            return r
        time.sleep(int(r.headers.get("retry-after", "1")))
    return r

Most official SDKs retry 429 automatically with backoff. If you build your own client, honor Retry-After rather than retrying immediately.