Errors and versioning
Errors#
Every error has a matching HTTP status and this body:
{ "error": "No identity is linked to that Minecraft account", "status": 404 }
The error text is meant for logs and people. Branch on status, not on the text.
| Status | Meaning |
|---|---|
400 |
the request is malformed: see error |
401 |
credentials are required and none were sent (with a WWW-Authenticate header) |
403 |
credentials are wrong, missing a User-Agent, or the caller isn't allowed to make this check |
404 |
the thing asked about doesn't exist, or the player's privacy settings hide it (deliberately indistinguishable) |
409 |
a precondition outside your request isn't met (the bot isn't in the server) |
429 |
too many unanswered access requests at once |
500 |
a bug on our side |
502 |
an upstream platform (Discord, Twitch, Patreon, YouTube) failed |
Versioning#
The API is versioned by path. /api/v2 is current. Within a version, responses only change in backwards-compatible
ways, such as new fields or new optional parameters. Ignore fields you don't know.
/api/v1/... and the original unversioned /api/... paths are deprecated. Their responses carry:
| Header | |
|---|---|
Deprecation: true |
the endpoint is deprecated |
Link: <…>; rel="successor-version" |
the equivalent v2 request |
Link: <…>; rel="deprecation" |
the migration guide |
Sunset: <date> |
when v1 starts applying players' privacy settings (present until that date) |
See Migrating to the v2 API for what changes on that date.