Rate limiting

market

Requests are limited per minute. The ceiling belongs to your account, not to an individual key: holding several keys buys no extra throughput, because they all draw on the same allowance. You are told your ceiling when your key is issued, and every response decided against it carries the number back in X-RateLimit-Limit — there is no separate endpoint to query it from.

Going over it answers 429 with code 42900 (RATE_LIMITED) and a Retry-After header. Back off for at least that long; do not retry in a tight loop.

There is also a second, much higher ceiling applied per client address, before authentication. It is there to stop an unauthenticated flood, and it sits well above any account's allowance, so a normal integration never meets it — but several accounts calling out through one shared address do share it.

The three quota headers

Header	Value
`X-RateLimit-Limit`	Your ceiling, in requests per minute.
`X-RateLimit-Remaining`	How much of it is left in the current window.
`X-RateLimit-Reset`	When the current window ends, as a Unix timestamp in seconds, UTC. Not a duration and not a date string.

They can be absent, and absent does not mean zero. If our rate-limit store becomes unavailable we keep serving traffic — under a coarser process-wide safety limit rather than by failing your requests — and while that is happening we do not know your quota state. We then send none of the three, rather than numbers we are not actually enforcing. Treat missing headers as no information this time: skip any quota arithmetic and fall back to reacting to a 429 if one arrives.

That is also how you can read a 429:


`429` with the quota headers	You went over your own ceiling. `Retry-After` is the earliest moment one more request fits — wait it out and your next request goes through.
`429` without them	Either we are degraded, or the shared per-address ceiling fired. Nothing was wrong with your request — back off for `Retry-After` and retry.

We deliberately do not use a second error code for the two cases, because your action is the same either way. If you need to know which one it was, quote the X-Request-Id: our logs record it.

Two things follow from Retry-After being the earliest such moment, and both surprise people:

It can be longer than one minute, even though your ceiling is per minute. The window slides rather than resetting on the clock, so the requests you already spent keep counting until they age out — they do not all expire at once at the top of a minute. At a ceiling of 1/min the wait reaches two minutes; at 60/min it is a little over one minute. It can also exceed that briefly right after we lower your ceiling, because the requests already counted were spent against the old, higher one. Treat the header as the number and do not derive a maximum from your ceiling.
You arrive with almost no allowance, not a fresh one. Retry-After points at the first instant there is room for a single request. How much you actually have when you get there depends on your ceiling, because the header is whole seconds and rounds up, so you arrive up to a second late and a little more has decayed in the meantime: at a ceiling of 5 you arrive with X-RateLimit-Remaining: 0, at 60 with 1, at 1000 with about 15. Read the header rather than assuming — and if you have a queue to drain, pace it against X-RateLimit-Remaining instead of retrying in a burst.

If you hold several keys, note that they share one ceiling (it is per account, not per key), so another of your keys can take that slot before your retry arrives.