Rate limits
How the token bucket works, what each request costs, and how to handle a 429.
On this page
The token bucket
Each caller has a bucket of tokens that refills steadily, every second, up to a ceiling. Every request spends tokens; when there are not enough left, the request is refused with 429 until the bucket has refilled enough. The bucket is kept in NexG's database, so the limit holds across every server answering you.
The refill rate is the key's limit in tokens per minute, set when the key is issued: 10 to 600, with 60 as the console's default. The bucket holds one minute's worth, so a quiet caller can spend a minute's tokens in a burst.
What requests cost
| Request | Scope | Tokens |
|---|---|---|
| Public reads: merchants, zones, experiences, services | public_read | 1 |
| Reading your orders | merchant_read | 3 |
| Booking a service (coming soon) | merchant_write | 5 |
Whose bucket
- A merchant key spends from its merchant's bucket, shared by all of that merchant's keys. It refills at the lowest limit among the merchant's active keys.
- A key without a merchant spends from the bucket of the person who issued it, shared by all of their keys without a merchant.
- No key: keyless callers share one bucket of 120 tokens a minute (or get 60 a minute for each address, where NexG identifies callers by IP at its edge). Fine for trying things, not for production.
So issuing more keys does not add capacity, and replacing a key does not refill the bucket. To raise a merchant's limit, issue a key with a higher limit and have the lower ones revoked.
An example
A merchant key at the default 60 tokens a minute can make 60 public reads a minute, or 20 order reads, or any mix. Polling orders once a minute costs 3, leaving 57 for catalogue reads.
When you are limited
A refused request gets 429 with code rate_limited and a Retry-After header: the whole seconds until enough tokens are back for that request. Wait at least that long before retrying. Retrying sooner is refused again and spends nothing, but it does not help.
- Spread scheduled work out instead of running it all on the minute.
- Cache public data on your side; it is cacheable for a minute or more anyway.
- Page through lists one page at a time rather than in parallel.
No remaining-token header yet
Responses do not say how many tokens are left. Track your own rate, and treat Retry-After as the answer when you hit the limit. See Errors for retry code.