Errors - Esheria

All errors use the normal API envelope.

{
  "status": "error",
  "data": null,
  "errors": [
    {
      "code": "unauthorized",
      "message": "Invalid API key"
    }
  ],
  "trace_id": "..."
}

Common Codes

Code	HTTP status	Meaning	Recovery
`unauthorized`	`401`	Missing or invalid API key	Check `x-api-key`, create or rotate a token in the dashboard
`workspace_not_active`	`403`	Workspace token is valid but the workspace is suspended or closed	Contact the workspace owner or Esheria support
`api_token_required`	`403`	A token/billing management endpoint was called without an API-token principal	Use a management token when billing is enabled
`credits_exhausted`	`402`	Workspace has no available credits for a billable request	Add credits or create a subscription/top-up checkout session from the dashboard
`billing_unavailable`	`503`	Billing ledger could not be checked or settled	Retry after operators resolve ledger availability
`validation_error`	`422`	Request payload or parameters do not match the schema	Compare with the API Reference and examples
`idempotency_key_required`	`400`	Mutating request omitted `idempotency-key`	Send a unique key for the request intent
`idempotency_key_conflict`	`409`	Same idempotency key reused with a different payload	Use a new key or replay the original request
`unsupported_capability`	`400` or `422`	Pack exists but does not support the requested workflow	Use another workflow or pack
`deprecated_api_route`	`410`	Caller used a non-regulatory route outside the public contract	Move to the Regulatory Pack API surface
`not_ready`	`503`	Runtime dependencies are missing or unhealthy	Check `/readyz` and retry after operators resolve readiness

Client Pattern

import httpx

try:
    response = httpx.get(
        f"{base_url}/api/v1/domain-packs",
        headers={"x-api-key": api_key},
        timeout=30,
    )
    response.raise_for_status()
except httpx.HTTPStatusError as exc:
    payload = exc.response.json()
    trace_id = payload.get("trace_id")
    errors = payload.get("errors", [])
    raise RuntimeError(f"Esheria API error trace_id={trace_id} errors={errors}") from exc

Support Checklist

When escalating an issue, include:

endpoint and method
timestamp
trace_id
HTTP status
first error code and message
sanitized request shape

Use https://dashboard.esheria.ai/ for token rotation, credit top-ups, usage inspection, and billing state before escalating a support issue. Do not include API keys or personal data unless your support channel explicitly requires and protects it.

​Common Codes

​Client Pattern

​Support Checklist

Common Codes

Client Pattern

Support Checklist