Errors Reference
Every error response — regardless of endpoint or status code — has exactly one JSON shape:
json
{ "error": "human-readable message" }There are no exceptions to this shape. It's always safe to read body.error
for a display-ready message, on any non-2xx response from any endpoint.
Status codes
| Status | Meaning | When it happens |
|---|---|---|
200 |
OK | Request succeeded. Response body is endpoint-specific JSON (see API Reference). |
400 |
Bad Request | A required path or query value was missing, empty, or invalid — e.g. calling
/api/player/ with no identifier, or /api/leaderboard
with a missing/unrecognized type. |
401 |
Unauthorized | The X-API-Key header was missing, malformed, or the key doesn't
match a valid, non-revoked key. See key revocation
if a previously-working key suddenly starts failing. |
404 |
Not Found | The requested resource doesn't exist — currently only returned by player lookup when no player has ever been seen with the given name/UUID. |
429 |
Too Many Requests | Your key exceeded its rate limit. Includes a Retry-After header
(seconds). See rate limits. |
503 |
Service Unavailable | Returned only by auction search when the auction house isn't available on the backend currently running the API — a server-side condition, not something wrong with your request. |
Handling errors in one place
Since the error shape never changes, most clients are best served by a single wrapper that every request goes through — see the JavaScript and Python examples, both of which centralize status handling into one helper function rather than repeating checks at every call site.