Guides

Errors

Errors use standard HTTP status codes and, almost always, one JSON shape.

The error body#

404 Not Found

{
  "error": {
    "code": "not_found",
    "message": "User not found."
  }
}

error.code is stable and machine-readable. Branch on it.
error.message is for people. Its wording can change, so never parse it.

Two exceptions#

Two errors are answered before a request reaches the API itself, and have a shorter body where error is a string:

Status	Body	When
429	`{"error":"rate limited"}`	Over the rate limit. Comes with `Retry-After`.
405	`{"error":"method not allowed"}`	A method other than `GET`, `POST`, `PUT`, `PATCH` or `DELETE`, such as `HEAD` or `OPTIONS`.

Handle both shapes:

const body = await response.json();
if (!response.ok) {
  const code = typeof body.error === 'string' ? body.error : body.error.code;
  throw new Error(`Rankd API ${response.status}: ${code}`);
}

body = response.json()
if not response.ok:
    error = body["error"]
    code = error if isinstance(error, str) else error["code"]
    raise RuntimeError(f"Rankd API {response.status_code}: {code}")

Status codes#

Status	Meaning
200	It worked.
304	Images only: the copy you have is current.
400	A parameter is invalid. `error.code` says which rule it broke.
401	The endpoint needs a Rankd account. It is not one of the public endpoints, or the path does not exist.
404	Not found, or not public. The API does not say which.
405	That method is not allowed.
429	Rate limited.
503	Part of the API is unavailable. Try again later.

A path that does not exist answers 401 unauthenticated, not 404, when you are not signed in: the API checks for access before it checks whether the route exists. Check your path if you get a 401 from what should be a public endpoint.

Error codes#

Code	Status	Meaning	From
`invalid_music_reference`	400	The music type or id is not one Rankd understands.	Get an album, song or artist Reviews of an album, song or artist
`invalid_query`	400	The search text is shorter than two characters.	Search the catalogue Search people Search lists
`invalid_type`	400	`type` is not one of the documented values.	Rankd Charts
`invalid_username`	400	Not something a Rankd username can be.	Look up a user by username
`unauthenticated`	401	The endpoint needs a Rankd account, or the path does not exist.	Any endpoint not on this site
`not_found`	404	It does not exist, or it is not public. The API does not say which.	9 endpoints
`catalogue_unavailable`	503	The music catalogue is not available. Try again later.	Search the catalogue
`database_unavailable`	503	The API cannot reach its database. Try again later.	Health check

Retrying#

429: wait for Retry-After seconds.
503: back off (1 s, 2 s, 4 s…) and try a few times.
400, 401, 404: do not retry; the answer will not change.