Exceptions

VenusNotLoadedException

public final class VenusNotLoadedException extends IllegalStateException {

    public VenusNotLoadedException() {
        super("VenusAPI is not loaded yet — wait for Venus to enable before calling VenusAPIProvider.get()");
    }
}

Thrown by VenusAPIProvider.get() when Venus has not published its API yet. It is an IllegalStateException, deliberately: calling the API too early is a programming error, not a recoverable condition, and runtime exceptions do not force try/catch noise into every call site.

Avoiding it

• Wait: VenusAPIProvider.getAsync().thenAccept(...). This is the recommended form and cannot throw.
• Probe: isLoaded() or getOrNull() for optional integrations.
• Catch: only when neither of the above fits, for example inside a third-party loader hook you do not control.

try {
    VenusApi api = VenusAPIProvider.get();
    api.punishments().kick(user, "Kicked by plugin");
} catch (VenusNotLoadedException notYet) {
    // Venus will load later; drop the request rather than queueing it forever.
    getLogger().warn("Venus is not loaded, skipping the kick");
}

What does not throw

Every read on the services returns empty data instead of failing:

• users().queryUserByUuid(...) — empty optional for a player Venus is not tracking (offline, exempt, or not yet built).
• checks().byName(...) — empty optional for an unknown name; a wrong name is not an error, because check names change between versions.
• history() — completes immediately with empty data when the datastore is disabled, and completes exceptionally only when the backend itself fails.
• server().tps() — reports the platform value, or 20 when the platform cannot answer.

See VenusAPIProvider for the full accessor and the overview for the guarantee list.