PlayerDB

Gotchas & limits

• The result code is a dotted string ("player.found", "minecraft.invalid_username", "xbox.not_found"), not a numeric status field — the first string-code envelope in this catalogue's Games & Comics quickstarts. Don't write a switch statement expecting integers.
• A not-found lookup is real HTTP 400, not 404, and its body sets "success": false but also "error": false — both flags present, neither one alone tells you the request failed. A live GET this run against a nonsense Minecraft username returned exactly this: {"message":"No Minecraft user could be found.","code":"minecraft.invalid_username","data":{},"success":false,"error":false}, 123 B. The same shape (different code) was confirmed live this run for Xbox (xbox.not_found) and Hytale (hytale.not_found).
• Hytale lookups really do resolve — and Hytale is the only one of the four platforms with two distinct 400 codes, splitting on the identifier's shape rather than on whether the player exists. Live this run, /player/hytale/nobody returned 200, 964 B, player.found, username Nobody, and alpha (853 B), Player1 (967 B) and xyz (869 B) resolved too; the payload is the richest of the four platforms, carrying a 20-field skin object (bodyCharacteristic, haircut, facialHair, overtop, cape, ...) alongside id/raw_id/username/avatar — though skin can itself be null on an otherwise-valid player (/player/hytale/qqqq, 200, 343 B). A well-formed but unknown identifier returns hytale.not_found (138 B, confirmed on Notch and admin); a malformed one is rejected before any lookup with hytale.invalid_identifier (131 B, {"message":"Invalid Hytale player identifier supplied.",...}). Probed live, the accepted shape is 3-16 characters, alphanumerics and underscore only — 1-2 and 17+ characters both give invalid_identifier, as do -, ., @ and a space, while abc_def gets far enough to return not_found. Both codes arrive as the same HTTP 400 with the same success:false/error:false pair, so code is the only field separating "you sent garbage" from "that player doesn't exist".
• Successful Minecraft lookups are cached hard: the live response above carried cache-control: public, max-age=2678400 (31 days) plus age: 181556 (already ~2 days stale when fetched this run) — a player's freshly-changed username can take up to a month to show through this API.
• Platform-specific data shows up in two places, so don't treat meta as the only place to look: each platform adds its own extra top-level keys next to the normalized ones, and meta then holds a payload whose shape is entirely provider-defined. id/username/avatar (plus the meta container itself) are the only four fields normalized across all four platforms, confirmed live this run against all four. Everything else is platform-specific, split across those two places. Extra top-level keys: Minecraft's skin_texture/properties/name_history, Hytale's skin, Xbox's modernGamertag/modernGamertagSuffix/uniqueModernGamertag. Inside meta: Steam's communityvisibilitystate/personaname/profileurl, Xbox's gamerscore/accounttier/xboxonerep/preferredcolor. Note raw_id is not a Minecraft-only field — it is shared by the two UUID-keyed platforms, Minecraft and Hytale, and absent on Steam and Xbox.