Errors

Every response under /api/v1/ that has a body is one envelope, success or error. A success carries data:

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

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

{
  "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 may change wording.

Two responses are not envelopes:

• A 304 Not Modified has no body at all: keep using the copy you have.
• GET /api/health answers a bare {"status": "ok"} (200) or {"status": "error"} (503), with no dataset_version.

Status codes

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
404	not_found	unknown item, paint, steam_id or system, or an unknown path under /api/v1/ (anywhere else, a 404 is this 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	the server failed: /v1/dump could not build the dataset download, or any endpoint hit an unexpected error; never cached, retry later

Real examples

curl https://truefloat.app/api/v1/items/7/45

{
  "dataset_version": "e9c25a6",
  "error": {"code": "not_found", "message": "no item def 7 paint 45"}
}

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"}
}