Concepts

Errors

Errors use normal HTTP status codes and always come with a short JSON body that says what went wrong.

The error body

Every error is a JSON object with an error string. Some carry one more field: retryAfter or resetIn on rate limits and lookup on player errors. The full shape is the Error object.

Response404

{
  "error": "Unknown item"
}

Status codes

Status	Meaning	What to do
200	Success.	Read the body.
202	A live lookup for a new player is still running.	Ask again in a few seconds.
304	Nothing changed since the ETag you sent.	Reuse your cached copy.
400	A parameter is missing or invalid.	Fix the request. The message names the parameter.
401	No API key, or the key is unknown or revoked.	Check the key and how you send it.
403	The key lacks a scope this request needs.	Use a key with that scope.
404	No such player, item or route.	Check the spelling. Usernames must exist on DonutSMP.
405	A method other than GET or HEAD.	Use GET.
414	The URL is longer than 2,048 characters.	Shorten the query.
429	Rate limit or lookup budget used up.	Wait for retry-after seconds.
500	Something broke on our side.	Retry after a short wait. Every 500 is logged on our side.

Validation errors

A 400 names every parameter that failed and why, separated by semicolons. Fix the request rather than retrying it.

GET /v1/players?limit=1000400

{
  "error": "limit: Too big: expected number to be <=200"
}

GET /v1/leaderboards/coins400

{
  "error": "board: Invalid option: expected one of \"money\"|\"deaths\"|\"playtime\"|\"placedBlocks\"|\"brokenBlocks\"|\"mobsKilled\"|\"kills\"|\"shards\"|\"bounties\""
}

What to retry

Retry 429 after retry-after seconds and 500 or network failures after a short backoff. Never retry 400, 401, 403 or 404 unchanged: the answer will be the same.

Player 404s are remembered

When DonutSMP says a player does not exist, that answer is kept for 10 minutes, so a typo does not start the same live lookup over and over.