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

# Errors

> Error envelope, stable codes, and retry behavior.

Every non-2xx response includes one `error` object.

## The error envelope

```json theme={null}
{
  "error": {
    "type": "invalid_request",
    "code": "transport.type.missing",
    "message": "Field `transport.type` is required.",
    "param": "transport.type",
    "request_id": "req_01HYZ..."
  }
}
```

| Field        | Type           | Notes                                                                                        |
| ------------ | -------------- | -------------------------------------------------------------------------------------------- |
| `type`       | string         | Broad, stable failure category. Not always one-to-one with HTTP status. See the table below. |
| `code`       | string         | Stable, machine-readable subcode in `lower_snake_case` / dotted form.                        |
| `message`    | string         | Human-readable. May change, so don't parse it.                                               |
| `param`      | string \| null | The offending request field (dot-path), when applicable.                                     |
| `request_id` | string         | `req_...`; include this when contacting support. Also echoed in `X-Request-Id`.              |

## Error types

`error.type` is one of a fixed set:

| HTTP | `error.type`          | When it happens                                                        |
| ---- | --------------------- | ---------------------------------------------------------------------- |
| 400  | `invalid_request`     | Malformed JSON, missing or invalid field.                              |
| 401  | `authentication`      | Missing, bad, or revoked API key.                                      |
| 402  | `quota_exceeded`      | Not enough credits, or billing isn't active for a credit-gated action. |
| 403  | `permission`          | Authenticated, but the key can't access this resource.                 |
| 404  | `not_found`           | Resource doesn't exist (or isn't in your scope).                       |
| 409  | `conflict`            | Idempotency conflict or a state-machine clash.                         |
| 422  | `unprocessable`       | Request shape is fine but the semantics are invalid.                   |
| 429  | `rate_limit`          | Per-key rate limit exceeded.                                           |
| 429  | `quota_exceeded`      | Per-org concurrency or usage quota exhausted.                          |
| 500  | `internal`            | Unexpected server error.                                               |
| 503  | `service_unavailable` | No capacity, or scheduled maintenance.                                 |

Two cases share `429`: `rate_limit` means you're calling too fast (back off and
retry), while `quota_exceeded` means a plan ceiling like concurrent sessions is
full (retrying won't help until capacity frees up). Branch on `error.type` to
tell them apart.

## Rate limits and retries

`429` and `503` responses may include `Retry-After` in seconds. Use that delay
before retrying.

## Quota exhaustion

A `quota_exceeded` error names the exhausted resource in `error.code`. Credit
exhaustion uses HTTP `402` with `code: "insufficient_credit_balance"`. Runtime
limits, such as concurrent sessions, use HTTP `429`.

```json theme={null}
{
  "error": {
    "type": "quota_exceeded",
    "code": "concurrent_sessions",
    "message": "Org org_... already has 5 concurrent sessions (max 5).",
    "param": null,
    "request_id": "req_..."
  }
}
```

## Handling errors

For API integrations, use the HTTP status and `error.code` for control flow.
`error.message` is written for humans and may change.

## Next

<Columns cols={2}>
  <Card title="Quotas" href="/reference/quotas" icon="gauge">
    Session caps, usage rounding, and credit behavior.
  </Card>

  <Card title="API Reference" href="/api-reference" icon="square-terminal">
    Endpoint schema generated from OpenAPI.
  </Card>
</Columns>