Guides
Errors & Status Codes
NoxAeApi uses standard HTTP status codes. Here's what each one means in the context of a Minecraft server.
Code
| Code | Meaning |
|---|---|
| 400Bad Request | Missing or malformed parameters — e.g. an invalid UUID, a non-numeric amount, or a missing required form field. |
| 404Not Found | The target resource does not exist — an unknown player UUID, world, plugin, or a player who is not currently online. |
| 409Conflict | The request conflicts with current state — e.g. creating a group that already exists, or debiting more than a player’s balance. |
| 424Failed Dependency | A required plugin dependency is not installed, so the action cannot be completed. |
| 500Internal Server Error | An unexpected error occurred while processing the request on the server. |
| 503Service Unavailable | An optional integration is disabled or not loaded (e.g. LuckPerms, NoxAuth, mcMMO, or an economy plugin). Do not retry — report it as unavailable. |
Dependency errors
NoxAeApi is modular. Many endpoints depend on other plugins being installed. When a dependency is missing, you'll typically see a 503 (optional integration disabled) or 424 (required dependency missing).
Don't retry dependency errors
A
503 means the integration (LuckPerms, NoxAuth, mcMMO, economy, PlaceholderAPI) is not present on this server. Retrying won't help — surface it to the user as unavailable.Error shape
Error responses return JSON with a human-readable message and the status code.
HTTP 503 Error Response
HTTP/1.1 503 Service Unavailable
Content-Type: application/json
{
"error": "LuckPerms is not installed or not loaded",
"status": 503
}