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
{ "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-idheader. Quote it when reporting a problem. issuesobject[]- For
validation_failed: each bad field or parameter, asfieldandmessage.
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.
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.
{ "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: aPOSTbody sent as anything butapplication/json. SendContent-Type: application/json.
429 rate_limited and the Retry-After header
HTTP/1.1 429 Too Many RequestsRetry-After: 23{ "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.
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
| Limit | Requests a minute | Counts |
|---|---|---|
Per key (GAME_API_RATE_LIMIT_PER_KEY) | 120 | Every request with the key, from every server of the game, reads and feedback together |
Every key together (GAME_API_RATE_LIMIT_TOTAL) | 1,200 | Every game's requests together: the developer API's ceiling |
| Per address, reads | 1,200 | GET requests from one address |
| Per address, writes | 240 | POST 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,/genresand/marketcome 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)./keyand feedback are never cached.Every key gets the same answer for the same path and query.
idsis read as a sorted set, soids=2,1andids=1,2,2share one entry.Every read carries an
ETag; read-cached ones also carryX-Cache(hit,stale,miss,sharedorbypass). SendIf-None-Matchwith the lastETag: an unchanged answer is304with 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
ccuchanges every 5 minutes at the fastest (the hot tier).Batch. Read many games in one
GET /games?ids=…(up to 100), never one/games/:ideach.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
| Status | Retry? | Do |
|---|---|---|
| 200, 304 | No | Use the answer (a 304 means keep the one you had) |
| 202 | No | Feedback stored; keep the receipt if you need it |
| 400, 413 | No | Fix the request |
| 401 | No | Stop; check the secret |
| 404 | No | The game is not tracked; drop it or have it opened |
| 429 | After Retry-After | Same request; same idempotency key for feedback |
| 5xx | With backoff (1, 2, 4 seconds) | Keep the last answer meanwhile |
| None | With backoff | Check 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