Skip to content

Errors

Every response under /api/v1/ with a body is an envelope. A success carries data:

{"dataset_version": "e9c25a6", "data": {}}

An error carries error, with a code and a message:

curl https://truefloat.app/api/v1/items/7/45
{
"dataset_version": "e9c25a6",
"error": {"code": "not_found", "message": "no item def 7 paint 45"}
}

Branch on the HTTP status and error.code. error.message is for humans and its wording may change.

Two responses are not envelopes:

  • A 304 Not Modified has no body: keep using the copy you have.
  • GET /api/health answers a bare {"status": "ok"} (200) or {"status": "error"} (503), with no dataset_version.
status code when
200 found, possibly empty. See Empty vs missing
304 If-None-Match equals the current ETag; no body
400 bad_request a required query param is missing (e.g. /resolve with neither slug nor market_hash_name), or a ?topic= that isn’t a known topic
404 not_found unknown item, paint, steam_id or system, or an unknown path under /api/v1/ (elsewhere, a 404 is the site’s HTML page)
422 bad_request a parameter is present but invalid or out of range: a seed outside 0..1000, a non-numeric def_index, a slug or market_hash_name over 200 characters
429 rate_limited over the rate limit. Wait Retry-After seconds, see Access & rate limits
503 internal_error a server error, such as /v1/dump failing to build. Never cached; retry later
curl https://truefloat.app/api/v1/resolve
{
"dataset_version": "e9c25a6",
"error": {
"code": "bad_request",
"message": "slug or market_hash_name required"
}
}

A 422, for a seed out of range:

curl https://truefloat.app/api/v1/items/7/44/seeds/1500
{
"dataset_version": "e9c25a6",
"error": {"code": "bad_request", "message": "seed must be 0..1000"}
}

And for a path parameter that isn’t a number:

curl https://truefloat.app/api/v1/items/ak47/44
{
"dataset_version": "e9c25a6",
"error": {"code": "bad_request", "message": "invalid parameters"}
}