Error Codes

Error format

All errors return a consistent structure:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description of what went wrong"
  }
}

Error reference

Client errors

Code	HTTP Status	Description
`BAD_REQUEST`	400	Missing or invalid query/path parameters
`MISSING_PARAMETER`	400	A required parameter was not provided
`VALIDATION`	400	Request body failed validation (wrong types, missing required fields)
`UNAUTHORIZED`	401	Missing, invalid, or revoked API key
`FORBIDDEN`	403	Valid key but insufficient permissions
`LIMIT_REACHED`	403	Tier feature limit reached (e.g. max portfolio entries)
`NOT_FOUND`	404	Resource not found or route doesn’t exist
`PLAYER_NOT_FOUND`	404	No Minecraft account exists with that username
`GUILD_NOT_FOUND`	404	No guild found matching the query
`NO_SKYBLOCK_DATA`	404	Player exists but has no SkyBlock profiles
`RATE_LIMITED`	429	Rate limit exceeded — check `Retry-After` header

Server / upstream errors

Code	HTTP Status	Description
`API_SETTINGS_DISABLED`	403	The player has disabled API access in their Hypixel settings
`INTERNAL_ERROR`	500	Unexpected server error
`DB_ERROR`	500	Database operation failed
`UPSTREAM_ERROR`	502	Upstream API (Hypixel or Mojang) returned an unspecified error
`UPSTREAM_AUTH_ERROR`	502	Upstream API key is invalid (transient — retry shortly)
`UPSTREAM_RATE_LIMITED`	502	Hypixel API rate limit exhausted — may include `Retry-After` header
`MOJANG_UNAVAILABLE`	502	Minecraft username service is temporarily unavailable
`TIMEOUT`	503	Upstream service timed out

Common errors

Missing API key

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "API key is required. Get one at https://developer.skytools.app/dashboard"
  }
}

Fix: Include your API key via X-API-Key or Authorization: Bearer header. See Authentication.

Invalid API key

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or revoked API key."
  }
}

Fix: Verify your key starts with sk_ and hasn’t been revoked. Generate a new key in the Dashboard.

Missing required parameter

{
  "success": false,
  "error": {
    "code": "BAD_REQUEST",
    "message": "item_id parameter is required"
  }
}

Fix: Check the endpoint documentation for required parameters.

Rate limit exceeded

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Max 60 requests per minute."
  }
}

Fix: Wait for the duration in the Retry-After header. See Rate Limits for optimization tips.

Player not found

{
  "success": false,
  "error": {
    "code": "PLAYER_NOT_FOUND",
    "message": "Player 'NotARealPlayer' not found"
  }
}

Fix: Check the spelling of the Minecraft username. The username must be a current, valid Mojang account.

No SkyBlock data

{
  "success": false,
  "error": {
    "code": "NO_SKYBLOCK_DATA",
    "message": "Player 'Technoblade' has no SkyBlock profiles"
  }
}

Fix: The player exists on Minecraft but has never played Hypixel SkyBlock, or has deleted all their profiles.

Guild not found

{
  "success": false,
  "error": {
    "code": "GUILD_NOT_FOUND",
    "message": "Guild 'FakeGuild' not found"
  }
}

Fix: Check the guild name spelling or try searching by player UUID instead.

API settings disabled

{
  "success": false,
  "error": {
    "code": "API_SETTINGS_DISABLED",
    "message": "This player has their API access disabled in Hypixel settings."
  }
}

Fix: The player must enable “API” in their Hypixel settings (/settings in-game → API). This is not something you can fix as an API consumer.

Mojang service unavailable

{
  "success": false,
  "error": {
    "code": "MOJANG_UNAVAILABLE",
    "message": "Minecraft username service is temporarily unavailable. Please try again later."
  }
}

Fix: The Mojang API is experiencing issues. Retry after a short delay. This is a transient error.

Route not found

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Route GET /v1/unknown not found. See GET / for available endpoints."
  }
}

Fix: Verify the endpoint URL against the API reference.

Upstream timeout (stale cache)

When an upstream service times out, the API may return stale cached data (up to 30 minutes old) instead of an error. Always check meta.stale to detect this.

If stale cached data is available, the response succeeds with extra metadata:

{
  "success": true,
  "data": { ... },
  "meta": {
    "cached": true,
    "api_version": "v1",
    "stale": true,
    "age_seconds": 245
  }
}

If no cached data is available, you’ll receive a 503:

{
  "success": false,
  "error": {
    "code": "TIMEOUT",
    "message": "Upstream service timed out. Please try again."
  }
}

Tier limit reached

{
  "success": false,
  "error": {
    "code": "LIMIT_REACHED",
    "message": "Portfolio limit reached for your tier (15). Upgrade for more."
  }
}

Fix: Upgrade your subscription or remove existing entries.

Getting started

Guides

Error format

Error reference

Client errors

Server / upstream errors

Common errors

Missing API key

Invalid API key

Missing required parameter

Rate limit exceeded

Player not found

No SkyBlock data

Guild not found

API settings disabled

Mojang service unavailable

Route not found

Upstream timeout (stale cache)

Tier limit reached