Rate limits
Every rate limit on the 0x API, with its rate and burst, who it applies to, and how 429 and Retry-After work.
Every limit is a token bucket. Each bucket holds a burst of requests and refills at rate per
second. The buckets live in Redis, so a limit holds across every API node. A request that finds its
bucket empty gets:
HTTP/1.1 429 Too Many Requests
Retry-After: 2
Content-Type: application/json
{"error": "rate limited", "retry_after_ms": 1500}Retry-After is in whole seconds (at least 1); retry_after_ms is the exact wait. Wait that long
before the next attempt.
The numbers below are the defaults in the code. 0x can tune them at runtime, globally or for one caller, so treat them as typical values, not guarantees. If a limit gets in your way, tell us about your use case.
#Global limits
Each request counts against one of these two buckets:
| Class | Applies to | Keyed by | Rate / burst |
|---|---|---|---|
auth | requests that check a password or create an account: POST /v1/oauth/token with grant_type=password, POST /v1/oauth/authorize, POST /v1/oauth/device, POST /v1/oauth/signup, POST /v1/oauth/guest | client IP | 2/s, burst 20 |
api | every other request | the bearer token (or the IP when anonymous) | 50/s, burst 300 |
So one token sustains about 50 requests a second, with bursts up to 300. Redeeming a refresh token,
authorization code or device code counts as an ordinary api request.
Account creation has a daily cap on top of the bucket: at most 5 new accounts per address per day
(429 slow_down).
#Per-feature limits
Some routes have their own bucket on top of the global one:
| Class | Route | Keyed by | Rate / burst |
|---|---|---|---|
playticket | POST /v1/apps/{appid}/play-ticket | account | 1/s, burst 30 |
worldticket | POST /v1/worlds/{universe}/ticket | account | 1 per 2 s, burst 30 |
iap_intent | POST /v1/apps/{appid}/iap/intents | account | 1 per 2 s, burst 20 |
topup | POST /v1/me/wallet/topups | account | 1 per 20 s, burst 10 |
topup-estimate | POST /v1/me/wallet/estimate | account | 1/s, burst 30 |
reviews | PUT / DELETE /v1/apps/{appid}/reviews/me | account | 1 per 30 s, burst 10 |
votes | PUT /v1/apps/{appid}/reviews/{id}/helpful | account | 1 per 2 s, burst 30 |
reports | POST /v1/apps/{appid}/report, .../reviews/{id}/report | account | 1 per 60 s, burst 5 |
reports_ip | the same | IP | 1 per 20 s, burst 20 |
issue_replies | POST /v1/listings/issues/{issue}/reply | account | 1 per 20 s, burst 10 |
visreports | POST /v1/visreports | account | 1 per 60 s, burst 5 |
csp | CSP reports (POST <site>-play.0x.limo/x1/csp) | IP | 1/s, burst 120 |
csp_site | the same | site | 20/s, burst 2000 |
xfer_site | anonymous transfer reports (POST .../x1/xfer) | IP | 1 per 10 s, burst 6 |
announce | swarm tracker announces (REST and push) | account | off by default |
#Other bounds
These caps aren't rates, but you'll hit them the same way. Each is listed on its route:
- Pending submissions: a listing with too many versions waiting for review gets
429. - Issue threads hold at most 200 messages.
- A wishlist holds 1000 games and server favourites 1000 entries.
GET /v1/content/{cid}/peersreturns at most 40 peers.- Lobby search returns at most 50 lobbies, or the
countfilter.
#Being a good client
- Cache public reads.
GET /v1/catalog/livesendsCache-Control: public, max-age=5andGET /v1/catalog/reviewssendsmax-age=30. Polling them faster gets you the same answer. - Use the push stream instead of polling for lobby, friend and invite changes.
- Batch where a batch route exists, such as
POST /v1/content/announcewith up to 1000 IDs. - Spread retries with jitter. When many clients retry on the same second, they hit the bucket together again.
