Errors and status codes

Read GymAssets status codes and stable error identifiers, then handle refusals without parsing human-readable messages.

A JSON refusal includes an error identifier. Additional fields such as detail, accepted, or expected explain how to correct the request.

{
  "error": "unknown_value",
  "parameter": "category",
  "value": "machines",
  "accepted": ["machine", "free-weight"]
}

Status	Meaning	What to do
`400`	The path, parameter, value, cursor, or requested format is invalid	Read `accepted`, `expected`, or `supported`
`401`	A key is missing, invalid, revoked, or the wrong type	Check the credential and where it was sent
`402`	The product allowance is exhausted	Handle the refusal and review account usage
`403`	The image request’s origin is not allowed	Update the key’s origins or use the intended key
`404`	The version, resource, member, figure, side, or asset does not exist	Correct the id or discover it from the API
`405`	The HTTP method is unsupported	Use `GET` or `HEAD`
`429`	A short burst limit refused the request	Retry after `retry-after`

Error handling

Use error as the stable identifier for programmatic error handling. detail is a human-readable description and may change over time.

`error`	Status	What happened	What to do
`bad_request`	`400`	The path is not one this API serves	`expected` lists every path that is
`unknown_parameter`	`400`	A query parameter this resource does not take	`accepted` lists the ones it does
`unknown_value`	`400`	A filter value outside its vocabulary	Read `accepted`, or fetch the vocabulary
`page_size_not_negotiable`	`400`	A page-size parameter was sent	Remove it and follow the cursor
`bad_cursor`	`400`	A cursor that did not come from a `next` field	Start the walk again
`too_many_terms`	`400`	`q` carried more words than search accepts	Search with fewer words
`unsupported_format`	`400`	An image extension the route does not serve	`supported` lists the ones it does
`unauthenticated`	`401`	No `Authorization` header, or nothing that parses as a key	Send the secret half as a bearer token
`wrong_credential`	`401`	A publishable key reached the data API	Send the secret half instead
`quota_exceeded`	`402`	The product allowance for the period is spent	Handle the refusal; `product` names which one
`origin_not_allowed`	`403`	An image request presented an origin the key does not list	Add the origin to the key, or use the intended key
`not_found`	`404`	No record in this collection has that id	Correct the id or discover it from the collection
`unknown_equipment`	`404`	No equipment has that id	`ids` names the endpoint that lists them
`unknown_resource`	`404`	No such collection or vocabulary	Read `expected` on a `bad_request` for the current paths
`unknown_version`	`404`	A version prefix other than `/v1` on the data API	Use `/v1`. The image host answers `not_found`
`method_not_allowed`	`405`	A method other than `GET`, `HEAD`, or `OPTIONS`	Read the `allow` header
`rate_limited`	`429`	Too many requests in a short window	Retry after `retry-after`

New identifiers are added over time. Handle an unrecognised error by its status code rather than assuming this list is complete.

A retired equipment id returns a plain not_found. There is no alias fallback to an id that replaced it.

Authentication errors

unauthenticated means a usable credential was not presented. wrong_credential means a publishable key reached the data API, which requires the secret half.

Unknown filter values

A collection filter outside its published vocabulary returns 400 unknown_value rather than an empty result. A misspelled filter and a valid filter with no matching records are answered differently.

Image diagnostics

A Musclegram image can return 200 while reporting a partial result:

x-muscles-not-drawn lists requested ids unavailable on that sheet.
x-muscles-unknown identifies the subset that is not a known muscle id.
x-width-clamped reports the requested width and the width actually served.
x-quota-status reports allowance degradation.