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

# Errors and reliability

> Handle authentication, permanent client errors, transient gateway failures, and ambiguous stateful writes.

export const ReliabilityMap = () => {
  const groups = [["Succeeded", "200", "Use the response. For a write, store the response that the client confirmed.", "border-emerald-200 bg-emerald-50 dark:border-emerald-900 dark:bg-emerald-950"], ["Repair request", "400 · 401 · 403 · 404 · 409 · 422", "Correct the request or state condition before retrying.", "border-stone-200 bg-stone-50 dark:border-zinc-800 dark:bg-zinc-900"], ["Back off", "429", "Retry with bounded exponential backoff and jitter.", "border-amber-200 bg-amber-50 dark:border-amber-900 dark:bg-amber-950"], ["Reconcile state", "502 · 503 · 504", "Treat reads as transient; treat failed writes as ambiguous until inspected.", "border-rose-200 bg-rose-50 dark:border-rose-900 dark:bg-rose-950"]];
  return <figure className="not-prose my-8 overflow-hidden rounded-2xl border border-stone-200 bg-white shadow-sm dark:border-zinc-800 dark:bg-zinc-950" aria-labelledby="reliability-caption">
      <div className="border-b border-stone-200 px-5 py-4 dark:border-zinc-800"><div className="text-xs font-semibold uppercase tracking-widest text-stone-500 dark:text-zinc-400">Reliability decision map</div><div className="mt-1 text-sm font-semibold text-stone-900 dark:text-zinc-100">Classify the response before deciding whether to retry</div></div>
      <div className="grid gap-3 p-4 md:grid-cols-2">
        {groups.map(group => <section key={group[0]} className={`rounded-xl border p-4 ${group[3]}`}>
            <div className="flex flex-wrap items-center justify-between gap-2"><div className="text-sm font-semibold text-stone-900 dark:text-zinc-100">{group[0]}</div><div className="font-mono text-xs text-stone-500 dark:text-zinc-400">{group[1]}</div></div>
            <div className="mt-2 text-xs leading-5 text-stone-600 dark:text-zinc-400">{group[2]}</div>
          </section>)}
      </div>
      <figcaption id="reliability-caption" className="border-t border-stone-200 px-5 py-3 text-xs text-stone-500 dark:border-zinc-800 dark:text-zinc-500">A transport failure on a mutating route can be operationally different from the same failure on a read.</figcaption>
    </figure>;
};

Adapt-1 responses are JSON. Clients should distinguish permanent request errors from transient infrastructure failures and ambiguous writes.

<ReliabilityMap />

## Authentication

A missing or invalid bearer token returns `401`. On hosted UAT, the proxy derives the session from the authenticated token and replaces a body `session_id`. Use fresh `domain_id` values and explicit run metadata for isolation under one token.

## Status families

| Status                | Client behavior                                   |
| --------------------- | ------------------------------------------------- |
| `200`                 | Request succeeded                                 |
| `400` / `422`         | Correct the payload or parameters before retrying |
| `401` / `403`         | Correct authentication or authorization           |
| `404`                 | Correct the route or resource identity            |
| `409`                 | Resolve the reported conflict/state condition     |
| `429`                 | Retry with bounded backoff and jitter             |
| `502` / `503` / `504` | Treat as transient; writes may be ambiguous       |

Not every route returns every status. Follow the generated endpoint contract when it is more specific.

## Reads and writes

`POST /api/v1/domains/{domain_id}/adapt/events`, normal domain events, feedback, and State writes can mutate persistent or adaptive state. Use stable identifiers and inspect available state before replaying an ambiguous write.

`POST /api/v1/domains/{domain_id}/adapt/predict` reads the current adaptive prediction without adding an observation.

## Isolation

For hosted UAT, a bearer token maps to one forced session. Isolate experiments and application workflows with fresh `domain_id` values and structured `run_id` metadata. Run one writer per online adaptive domain unless interleaving is intended.

## Recovery sequence

```text theme={null}
classify response -> back off if transient -> inspect state if write was ambiguous -> resume from checkpoint
```

See [Operate stateful and adaptive workflows](/docs/neuroadapt/operational-behavior-and-retries) for ordering, identifiers, and reset behavior.

## Public API limits

| Limit                    | Contract                                                                     |
| ------------------------ | ---------------------------------------------------------------------------- |
| Batch store              | 1–50 items                                                                   |
| Query `top_k`            | 1–100                                                                        |
| Domain event relations   | Up to 1,024 relation objects                                                 |
| Memory and Domain writes | Keep structured JSON payloads compact; send images through the Vision routes |

A `413` response means the request exceeded its payload limit. A `429` response means admission capacity was reached; honor `Retry-After` before using bounded exponential backoff.

Do not blindly retry mutating calls. Batch store is non-atomic, so successful items can remain stored when a later item fails. Reconcile a failed write from its available state or returned item results before resubmitting it.