0xDocs 0x.limo

Docs / REST API

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
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:

ClassApplies toKeyed byRate / burst
authrequests 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/guestclient IP2/s, burst 20
apievery other requestthe 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:

ClassRouteKeyed byRate / burst
playticketPOST /v1/apps/{appid}/play-ticketaccount1/s, burst 30
worldticketPOST /v1/worlds/{universe}/ticketaccount1 per 2 s, burst 30
iap_intentPOST /v1/apps/{appid}/iap/intentsaccount1 per 2 s, burst 20
topupPOST /v1/me/wallet/topupsaccount1 per 20 s, burst 10
topup-estimatePOST /v1/me/wallet/estimateaccount1/s, burst 30
reviewsPUT / DELETE /v1/apps/{appid}/reviews/meaccount1 per 30 s, burst 10
votesPUT /v1/apps/{appid}/reviews/{id}/helpfulaccount1 per 2 s, burst 30
reportsPOST /v1/apps/{appid}/report, .../reviews/{id}/reportaccount1 per 60 s, burst 5
reports_ipthe sameIP1 per 20 s, burst 20
issue_repliesPOST /v1/listings/issues/{issue}/replyaccount1 per 20 s, burst 10
visreportsPOST /v1/visreportsaccount1 per 60 s, burst 5
cspCSP reports (POST <site>-play.0x.limo/x1/csp)IP1/s, burst 120
csp_sitethe samesite20/s, burst 2000
xfer_siteanonymous transfer reports (POST .../x1/xfer)IP1 per 10 s, burst 6
announceswarm tracker announces (REST and push)accountoff 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}/peers returns at most 40 peers.
  • Lobby search returns at most 50 lobbies, or the count filter.

#Being a good client

  • Cache public reads. GET /v1/catalog/live sends Cache-Control: public, max-age=5 and GET /v1/catalog/reviews sends max-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/announce with up to 1000 IDs.
  • Spread retries with jitter. When many clients retry on the same second, they hit the bucket together again.