Error Reference

Error categories, HTTP status codes, JSON error envelope shapes, and how errors surface through the hoziron-cli CLI.

Two JSON error envelope shapes

The API returns errors in two different shapes depending on which layer rejected the request. Both are JSON with a top-level "error" key, but the value differs — check the type of error before parsing it as an object.

1. Application/business-logic errors (routing, agents, workflows, catalog, config, memory, PII — everything that goes through hoziron_core::CoreError):

{
  "error": {
    "category": "ValidationError",
    "message": "server.listen '...' is not a valid socket address",
    "details": { "field": "server.listen" }
  }
}

category is the Rust ErrorCategory variant name (see table below). details is a free-form string map with context (field names, entity IDs) — always present, may be empty. Built by error_response() in crates/surfaces/hoziron-api/src/routes.rs.

2. Auth-middleware / rate-limit errors (401, 403, 429 raised by the shared HTTP middleware before a request reaches application code — these never construct a CoreError at all):

{ "error": "forbidden", "message": "Role 'viewer' cannot perform 'agent:create'" }

Here error is a short string code ("unauthorized", "forbidden", "too_many_requests", "internal_error"), not an object — there is no error.category. too_many_requests also carries a retry_after_secs field. Built by crates/infra/hoziron-http/src/responses.rs, shared across the API, registry, and every surface using the common auth middleware.

Practical implication: don't write a client that unconditionally reads error.category/error.message as if the shape is uniform — for shape 2, error is a plain string and the human-readable text is at the sibling key message, not nested under error. (The bundled hoziron-cli CLI's HTTP client currently reads body["error"] ["message"] uniformly; for shape 2 responses this indexes into a JSON string, evaluates to null, and the CLI prints a generic "Unknown error" instead of the real message — a known quirk of the current client, not a documented API contract you should rely on.)

HTTP Status Codes

error_response() category → status mapping

Only these ErrorCategory variants get a specific status code; every other variant falls through to 500 Internal Server Error:

Full ErrorCategory enum

hoziron_core::ErrorCategory — every application-level error carries exactly one of these:

There is no TriggerMismatch variant — agents do not declare accepted invocation sources; see invocation-model.md.

CLI error surfacing

The hoziron-cli CLI has its own error enum (bin/hoziron-cli/src/error.rs), deliberately independent of hoziron_core/kernel error types (kernel errors must never leak past the core boundary — see the Kernel Isolation Rule):

Exit codes: 0 success, 1 any CliError, 2 argument-parsing error (clap), 130 SIGINT (Ctrl+C).

Related:

• Troubleshooting
• config.toml reference — Validation Rules
• RBAC
• Provider troubleshooting