Minecraft Profile API

{
  "success": true,
  "cached": true,
  "java": { "username": "jeb_", "uuid": "...", "skin_url": "...", "cape_url": "..." },
  "bedrock": { "username": "...", "xuid_decimal": "...", "floodgate_uuid": "..." }
}

java | bedrock: optional object; fields may be null

• limit: ~180 / 60s / IP
• uncached_limit: 45 / 60s / IP
• update_cooldown: 3600s / profile
• HTTP 429 + Retry-After

async function lookupPlayer(identifier, edition = 'java') {
  const url = new URL('/minecraft-api', 'https://vrc.lol');
  url.search = new URLSearchParams({ username: identifier, type: edition });
  const response = await fetch(url, { headers: { Accept: 'application/json' } });
  const data = await response.json();
  if (!response.ok || !data.success) {
    const retryAfter = response.headers.get('Retry-After');
    throw new Error([data.code || response.status, data.error,
      retryAfter ? 'Retry after ' + retryAfter + ' seconds' : ''].filter(Boolean).join(': '));
  }
  const player = data[edition];
  if (!player) return null;
  return {
    player,
    skinURL: player.skin_url ? new URL(player.skin_url, url.origin).href : null,
    capeURL: player.cape_url ? new URL(player.cape_url, url.origin).href : null
  };
}

Go client: bound the request time

client := &http.Client{Timeout: 10 * time.Second}
endpoint := "https://vrc.lol/minecraft-api?" + url.Values{
    "username": {"Notch"}, "type": {"java"},
}.Encode()
response, err := client.Get(endpoint)
if err != nil { return err }
defer response.Body.Close()
if response.StatusCode != http.StatusOK {
    return fmt.Errorf("lookup HTTP %d; retry-after=%s",
        response.StatusCode, response.Header.Get("Retry-After"))
}
var profile struct {
    Success bool `json:"success"`
    Java *struct { UUID string `json:"uuid"` } `json:"java"`
}
if err := json.NewDecoder(response.Body).Decode(&profile); err != nil { return err }
if !profile.Success || profile.Java == nil { return fmt.Errorf("Java profile unavailable") }

The Go snippet belongs inside a function returning an error and uses net/http, net/url, time, fmt and encoding/json.

{
  "success": false,
  "status": 400,
  "code": "MISSING_PARAMETER",
  "error": "Missing required parameter: username"
}

• 400: fix the request. Codes include MISSING_PARAMETER, INVALID_INPUT_FORMAT, INVALID_TYPE_FILTER, INVALID_CAPE_HASH and INVALID_CAPE_VIEW.
• 404: the requested profile or asset was unavailable. Examples: CACHE_PROFILE_NOT_FOUND, TEXTURE_NOT_FOUND, CAPE_NOT_FOUND. Do not retry in a tight loop.
• 429: wait for Retry-After. RATE_LIMITED, MISS_RATE_LIMITED and UPDATE_COOLDOWN describe different limits.
• 502 / 503: a refresh or upstream texture provider may be temporarily unavailable. Use a bounded retry with backoff; honour Retry-After when present.

1. URL-encode identifiers and specify the edition.
2. Check HTTP status, JSON success and the selected edition before reading fields.
3. Store UUIDs and XUIDs as strings; resolve relative image URLs.
4. Cache successful responses and textures. Use the response cache headers rather than a fixed refresh loop.
5. Respect rate-limit headers and Retry-After. The standard profile budget is 180 requests per minute per IP, with a separate 45 uncached lookups per minute budget; these limits can be configured.
6. Keep account permissions separate from public appearance data. A texture, cached owner list or matching name is not authentication.