> ## Documentation Index
> Fetch the complete documentation index at: https://docs.esheria.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Interpret API error envelopes and recover from common authentication, idempotency, validation, and capability failures.

All errors use the normal API envelope.

```json theme={null}
{
  "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

```python theme={null}
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.