Errors and reliability

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

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

Authentication

A missing or invalid bearer token returns 401. On the hosted API, 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 the hosted API, 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

classify response → back off if transient → inspect state if write was ambiguous → resume from checkpoint

See Operate stateful and adaptive workflows 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.