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.734.917 is tracked but no copy of it is stored" }
Status and slugMeaning 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.734.917; desktop wants version-ddf602d9cfe44005.
400 unknown_format An offsets format that does not exist. Supported: json, hpp, cs, txt.
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. Normal for a release published in the last few hours: dumps follow a release rather than accompanying it. Retry later — do not substitute a neighbouring version's offsets.
404 format_not_found That build has a dump, but not in that format. The body lists the formats it does have.
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 That platform will not have offsets — macOS today. Deliberately not a 404: the route is right and the version exists, the capability does not. Do not retry.
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://www.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.