Errors & troubleshooting

What common errors mean and how to clear them.

401 or invalid key: confirm the EVAL- or paid key, then check that it remains active and has not expired. Client 0.5.0 trims accidental leading and trailing whitespace without changing the stored key.

Shape mismatch: n is the observed-response width. n_controls is the writable width. assign must map every control once and serve every observable. Bounds live in writable-configuration space and require explicit units.

409 idempotency conflict: the same request_id was reused with a different payload. Generate one identifier per logical action and reuse it only across transport retries.

409 session unavailable: hosted session state was lost during a deployment or the request reached a different machine. Start a fresh session; never continue from an unknown controller state.

OutOfEnvelope: inspect the attached preflight or contract report. A declined session returns its safest known configuration. A boundary preflight is not a decline, but it is not evidence-backed fit.

No improvement: verify measurement conventions, target feasibility, component-level readout quality, same-cycle timing, and whether the declaration matches a registered evidence cell.

Timeout: hosted evaluation adds one HTTPS round trip per update. Move on-prem when the loop cannot tolerate that latency.