Errors, limits and polling

Every error the developer API answers with its body, the rate limits of a game's key, Retry-After, how answers are cached, and how often a game should poll.

Get started

Every refusal from the developer API has the same JSON shape and a stable error.code meant for code. This page lists each one, the order the checks run in, the limits behind 429, how answers are cached, and how often a game should ask.

How an error answer looks

JSON
{  "error": {    "code": "validation_failed",    "message": "Invalid request",    "requestId": "0b6f2d4e-8a1c-4e5f-9d3b-7c2a1e0f4b6d",    "issues": [{ "field": "ids", "message": "Send at most 100 universe ids" }]  }}

error

codestring
Stable, for code: validation_failed, invalid_request, unauthenticated, not_found, payload_too_large, uri_too_long, unsupported_media_type, rate_limited, unavailable, timeout, internal.
messagestring
A sentence for a person. Never repeats the key or the value refused.
requestIdstring
The id the platform logged the request under, also in the x-request-id header. Quote it when reporting a problem.
issuesobject[]
For validation_failed: each bad field or parameter, as field and message.

The order the developer API checks a request in

Each check runs only when the one before passed, so a request refused early costs less, and only a request with a valid key counts against the key's limits and appears in its usage.

The checks before a developer API answer. A request is checked in this order. Its address must be at most 2,048 characters, else 414. A body must be JSON, else 415 or 400. The per-address limit comes next, else 429. A body over 16 KiB is refused with 413. Then the key is looked up, else 401. Then the key's own limit and the shared limit of every key are counted, else 429. Then the parameters or body are checked, else 400 validation_failed. Last comes the answer, from the read cache or the database: 200, 202, 304 or 404.

400 validation_failed: a bad parameter or body

A query parameter, a path id or a feedback body is not what it should be; issues names each. Examples: ids with more than 100 ids or a non-number, an unknown sort, a limit over 100, a range that does not exist, a feedback text over 2,000 characters, an unknown body field. A body that is not valid JSON at all is 400 invalid_request. Fix the request; retrying it unchanged will not help.

401 unauthenticated: the key was refused

The developer API's 401 error body is the JSON below. Its unauthenticated code means the game's API key was refused.

JSON
{  "error": {    "code": "unauthenticated",    "message": "Send the game's API key as Authorization: Bearer; the key sent is missing, wrong or revoked",    "requestId": "…"  }}

One answer for a missing, malformed, wrong or revoked key, and for the key of a game that left the studio's catalog. Stop asking and check the BlockoutApiKey secret: the key was probably rotated or revoked. See Getting a game's API key.

404 not_found: an untracked game

GET /games/:id and /games/:id/history for a game the platform does not track, with message Game not found, and any path the API does not serve. The API never looks a game up on Roblox for a key. Do not retry; ask a studio owner to open the game's page in the panel to start tracking it.

413 payload_too_large: a body over 16 KiB

Any request whose Content-Length is over 16 KiB, refused before the key is looked up, with message The body is larger than the developer API accepts. Send less.

414 uri_too_long and 415 unsupported_media_type

  • 414 uri_too_long: the address with its query is over 2,048 characters. 100 ids of up to 10 digits fit with room to spare; a longer query is a bug.

  • 415 unsupported_media_type: a POST body sent as anything but application/json. Send Content-Type: application/json.

429 rate_limited and the Retry-After header

HTTP
HTTP/1.1 429 Too Many RequestsRetry-After: 23
JSON
{  "error": {    "code": "rate_limited",    "message": "Too many requests with this key; wait and retry",    "requestId": "…"  }}

A limit below was reached. Retry-After is the whole number of seconds (at least 1) until the minute's count starts again; when two limits refuse at once, it is the longer wait. Wait that long before any request, then retry with the same request (for feedback, the same idempotency key). The per-address limit answers the same code with message Too many requests; wait a moment and try again.

A 429 and its Retry-After. The game server sends a request after the key's 120 for the minute are spent. The API answers 429 rate_limited with Retry-After, the seconds until the minute's count starts again. The server sends nothing in that time, then sends the same request again, with the same idempotency key for feedback, and is answered.

5xx: the platform could not answer

503 unavailable or timeout when the database is busy or a request took too long, with Retry-After: 5; 500 internal for anything else, with no detail beyond the request id. Keep the last answer you have and retry later with backoff.

The rate limits of a game's key

LimitRequests a minuteCounts
Per key (GAME_API_RATE_LIMIT_PER_KEY)120Every request with the key, from every server of the game, reads and feedback together
Every key together (GAME_API_RATE_LIMIT_TOTAL)1,200Every game's requests together: the developer API's ceiling
Per address, reads1,200GET requests from one address
Per address, writes240POST requests from one address

Each limit counts in fixed one-minute windows, shared by every replica of the API. The per-address limit is checked first; then the key is looked up; then the key's own and the shared limits are counted together. A request with a valid key counts whatever it answers: a cached answer and a 304 count too. GET /developer/v1/key reports the key's limit as limits.perMinute.

What happens to the limits when their store is down

The counts live in Redis. When Redis cannot be reached, a request goes ahead uncounted, and the outage is logged once a minute rather than once a request: the limits protect the API and must not be the reason it stops answering. The key itself is still checked on every request.

How the developer API caches answers

  • The reads of /games, /games/:id, its history, /genres and /market come from the platform's read cache: an answer is fresh for 60 seconds, and replaced on the next read after the collector stores new market data (at most every 30 seconds). /key and feedback are never cached.

  • Every key gets the same answer for the same path and query. ids is read as a sorted set, so ids=2,1 and ids=1,2,2 share one entry.

  • Every read carries an ETag; read-cached ones also carry X-Cache (hit, stale, miss, shared or bypass). Send If-None-Match with the last ETag: an unchanged answer is 304 with no body.

  • The key is checked before any cached answer is read, so a revoked key stops at once whatever is cached.

How often a game should poll the developer API

  • The 120 a minute is for the whole game, not per server. A game whose every server polled on its own would run out with a few hundred servers.

  • Read through one shared cache. The Template's platform service keeps one answer for every server in MemoryStore, so one server asks the platform per query per minute.

  • At most once a minute per query. The data changes only when the collector stores new readings, and a game's ccu changes every 5 minutes at the fastest (the hot tier).

  • Batch. Read many games in one GET /games?ids=… (up to 100), never one /games/:id each.

  • Ask a fixed set of queries. Each distinct query (route and parameters) is its own cache entry and its own request.

  • On 429, wait Retry-After. On 401, stop. On 5xx, keep the last answer and back off.

What to do with each status

StatusRetry?Do
200, 304NoUse the answer (a 304 means keep the one you had)
202NoFeedback stored; keep the receipt if you need it
400, 413NoFix the request
401NoStop; check the secret
404NoThe game is not tracked; drop it or have it opened
429After Retry-AfterSame request; same idempotency key for feedback
5xxWith backoff (1, 2, 4 seconds)Keep the last answer meanwhile
NoneWith backoffCheck Allow HTTP Requests and the network

Seeing a key's requests and refusals

The game's Developer tab shows the key in use's requests in the last 24 hours and 7 days, how many were refused or failed, how many were rate limited, and a count for each route, from counts kept per UTC hour for eight days. Requests with a bad key belong to no key and are not counted, and neither are requests refused by the per-address limit or for their size, which are refused before the key is read. A key's own 429 is counted as rate limited. A climbing rate-limited count means the game asks too often.

Updated