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.

SDK Exception Mapping (Python & TypeScript)

Both the Python SDK (noxaeapi-sdk) and TypeScript SDK (@wumx-labs/noxaeapi-sdk) map HTTP responses directly to structured exception classes:

HTTP Status	Python Exception	TypeScript Class	Description
400	NoxAeApiError	NoxAeApiError	Invalid payload or unparseable parameters.
401	NoxAeApiUnauthorizedError	NoxAeApiUnauthorizedError	Missing or rejected API key in the "key" header.
403	NoxAeApiForbiddenError	NoxAeApiForbiddenError	Key does not have admin permissions or action is blocked.
404	NoxAeApiNotFoundError	NoxAeApiNotFoundError	Resource, player, world, or currency does not exist.
409	NoxAeApiError	NoxAeApiError	State conflict, e.g. group name already exists in LuckPerms.
424	NoxAeApiError	NoxAeApiError	Required underlying plugin (e.g. ExcellentEconomy) is missing.
429	NoxAeApiRateLimitError	NoxAeApiRateLimitError	Rate limit exceeded. Contains retry_after_ms / retryAfterMs.
500	NoxAeApiServerError	NoxAeApiServerError	Unexpected server-side error during execution.
503	NoxAeApiServerError	NoxAeApiServerError	Plugin not loaded or module temporarily disabled.
Network	NoxAeApiNetworkError	NoxAeApiNetworkError	Socket connection failed, ECONNREFUSED, or timeout.

Catching Exceptions in Python

python_error_handling.py

from noxaeapi_sdk import (
    NoxAeApiError,
    NoxAeApiUnauthorizedError,
    NoxAeApiForbiddenError,
    NoxAeApiNotFoundError,
    NoxAeApiRateLimitError,
    NoxAeApiServerError,
    NoxAeApiNetworkError,
)

try:
    client.players.kick(uuid, reason="Maintenance")
except NoxAeApiUnauthorizedError:
    print("API key rejected — re-authenticate.")
except NoxAeApiForbiddenError:
    print("This key is not an admin key.")
except NoxAeApiNotFoundError:
    print("Player not found or not online.")
except NoxAeApiRateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after_ms}ms")
except NoxAeApiServerError as e:
    print(f"Server-side failure ({e.status}): {e.body}")
except NoxAeApiNetworkError as e:
    print(f"Failed to reach server: {e.cause}")
except NoxAeApiError as e:
    print(f"Generic NoxAeApi error: {e}")

Catching Exceptions in TypeScript

ts_error_handling.ts

import {
  NoxAeApiError,
  NoxAeApiUnauthorizedError,
  NoxAeApiForbiddenError,
  NoxAeApiNotFoundError,
  NoxAeApiRateLimitError,
  NoxAeApiServerError,
  NoxAeApiNetworkError,
} from "@wumx-labs/noxaeapi-sdk";

try {
  await client.players.kick(uuid, "Maintenance");
} catch (err) {
  if (err instanceof NoxAeApiUnauthorizedError) {
    console.error("Invalid or missing API key");
  } else if (err instanceof NoxAeApiForbiddenError) {
    console.error("Action requires admin privileges");
  } else if (err instanceof NoxAeApiRateLimitError) {
    console.warn(`Rate limited. Retry after ${err.retryAfterMs}ms`);
  } else if (err instanceof NoxAeApiServerError) {
    console.error(`Server error ${err.status}: ${err.message}`);
  } else if (err instanceof NoxAeApiNetworkError) {
    console.error("Network unreachable:", err.cause);
  } else {
    console.error("Unknown API error:", err);
  }
}

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
}

Code#

SDK Exception Mapping (Python & TypeScript)#

Catching Exceptions in Python

Catching Exceptions in TypeScript

Dependency errors#

Error shape#

Code

SDK Exception Mapping (Python & TypeScript)

Dependency errors

Error shape