Failures and edge cases

Windows · macOS · Android · home

Every non-200 this API produces, and what to do about it. Errors are JSON and always carry a stable error slug — branch on that, never on the prose in message.

{ "error": "not_stored", "message": "2.738.1397 is tracked but no copy of it is stored" }

Status and slug	Meaning and response
`400 unknown_platform`	The platform segment is not one this tracker knows. The body lists the valid slugs and which of them this deployment actually tracks. Fix the request.
`400 unsupported_abi`	You asked for an ABI this tracker does not follow. Android tracks `x86_64` only and desktop has no ABI variants at all, so this refuses rather than returning something that will not run. Fix the request.
`400 bad_version`	The version in the path is not shaped like that platform's identifier (or the word `latest`). Nothing was looked up. Android wants `2.738.1397`; desktop wants `version-c5aecda2245e4fae`.
`400 unknown_file`	Not an offsets file or format. The short formats are `json`, `hpp`, `cs`, `txt`; full names such as `fflags.hpp` work too. The body lists them.
`400 unknown_tier`	`tier` must be `best`, `verified` or `default`.
`400 unknown_event_type` / `400 bad_since`	A filter on `/api/v1/events` that does not parse. The body lists the event types.
`400 tier_not_accepted`	An upload asked to write the default tier. Uploads only ever create verified sets.
`400 rejected`	An upload was refused — most often because its `offsets.json` names a different build than the URL. The existing set is untouched.
`401 unauthorized`	A token was required and yours was missing or wrong. On `/internal/` routes it also means no `HTTP_TOKEN` is configured at all, in which case writes are disabled outright. Not retryable.
`404 unknown_version`	A well-formed version this tracker has never seen. Usually a typo, or — on desktop — a build from before this server started watching. See the note about `DeployHistory.txt` on the contents page.
`404 not_stored`	Known version, no copy kept — normally because it was pruned, or because it shipped no `x86_64` artifact and was never worth archiving. Call `/api/v1/{platform}/files` and pick something that exists.
`404 offsets_not_found`	No dump for that build in any tier. Normal for a release published in the last hour or so: dumps follow a release rather than accompanying it. Retry later — do not substitute a neighbouring version's offsets.
`404 offsets_not_verified`	You asked for `tier=verified` and the build has only a default set. The body lists `availableTiers`. Wait for a verified set, or accept default deliberately.
`404 tier_not_found`	You asked for `tier=default` and the build has only a verified set.
`404 file_not_found`	The served set exists but has no such file. The body lists the files and tiers it does have.
`404 package_not_stored`	An extra Windows package this deployment does not keep. The body says which it does.
`409 already_live`	Operator route: a build that has been live cannot be flagged upcoming.
`404 not_found`	No such route. Check the path against Endpoints.
`405 method_not_allowed`	Right path, wrong verb. Publishing offsets is a `POST`.
`413 payload_too_large`	An offsets upload over the size cap. A real dump is a few tens of kilobytes.
`501 offsets_unsupported`	No offsets have ever been published for that platform — macOS, until its first verified set. Deliberately not a `404`: the route is right, the capability is what is missing. It turns into a normal listing by itself once a set is published.
`503 platform_not_tracked`	A real platform this deployment is configured not to watch. An operator decision, not a fault. The body lists what is tracked.
`503 no_installable_build`	Nothing usable has been confirmed yet — a fresh deployment before its first full cycle, or, on Android, a genuine run of arm-only releases. Keep whatever you have and retry later.
`503 archive_disabled`	This deployment stores no files for that platform, so downloads cannot work. Metadata endpoints still answer. An operator decision, not a fault.
`502 resolution_failed`	Upstream could not be reached while resolving a URL. Transient. Retry with backoff.
`500 internal_error`	A bug here. Retry once; if it persists, tell the operator which URL did it.

States that look like errors and are not

installable: false on the current Android version. Roblox shipped a build with no x86_64 library. Correct behaviour is to stay on the older installable build, which is what /api/v1/android/current returns, with heldBack explaining it.
version: null from /version. No poll has completed for that platform yet. Wait one cycle (60s).
An empty files array. Nothing archived yet for that platform. It fills in once a build is confirmed and copied.
An empty offsets list on a supported platform. Nothing published yet — different from 501, which means never.
sha256: "". Unknown — not zero, and not failed. Treat as unpinned. Offsets indexed straight from the bucket have null for the same reason: we never saw those bytes.
A short desktop history. Not a gap in the data. Roblox redacted the build hashes from its deploy log, so desktop history genuinely begins when this server first polled.

Retrying

Retry 502, 503 and network failures with exponential backoff — a few seconds, then a minute, then give up for this cycle and keep the version you have. Do not retry 400, 401, 404 or 501; nothing about them will change on a second attempt.

A download that dies mid-transfer is worth retrying immediately: the redirect target supports range requests, so curl -C - resumes rather than starting over.

Is the server itself alright?

If answers look stale, check https://rbxoffsets.com/healthz. It returns 503 when the poll loop has stalled, which is the difference between "Roblox has not shipped anything" and "this tracker stopped looking". Each platform page also shows the loop's state directly.

Stability of this API

Paths are versioned. /api/v1/ keeps its current shape.
Fields may be added without warning. Ignore unknown ones rather than failing.
Field removals or meaning changes go to /api/v2/.
The pre-platform forms — /download/{version} for Android — keep answering.
Timestamps are ISO 8601 UTC; *EpochMs variants are milliseconds.