CONSOLE V1 / CUSTOMER GUIDE

Troubleshooting & reconciliation

Recover by inspecting persisted state, not by assuming the last request failed.

401 or expired session

Confirm the private console origin and cookie jar, not the static docs origin. Reauthenticate when the eight-hour cookie expires; logout revokes one session. An invalid bearer token does not fall back to a valid cookie. Never paste passwords, cookies or tokens into an issue report.

403 same_origin_required

For login/signup and session mutations send Origin exactly equal to the configured origin, X-Console-CSRF:1 and application/json. DELETE may omit JSON. Bodyless POST still needs the header; send {}. Do not add wildcard CORS or disable CSRF. A source-token scope denial is different: use only the source's own ingest path and its own operation receipts.

Registration unavailable or throttled

Check /session/options. Signup is disabled by default; duplicates and the 32-workspace cap intentionally use a generic error. Validate ASCII username length and UTF-8 password/workspace-name byte lengths. Login/signup share 20 attempts per minute; wait rather than retrying aggressively. A new workspace begins empty and cannot query another workspace's evidence.

Accepted but still pending

HTTP 202 proves durable inbox acceptance only. Poll /operations/{id}; inspect each lane status, attempts, last_error and receipt. Do not acknowledge upstream until committed. Recover or reconcile the failing dependency before source progress. A durable quarantine disposition can commit without normalized events; inspect accepted/replayed/quarantined counts, not just HTTP success.

Replay or native-key conflict

Identical source-key/content replay should not duplicate durable detections. Different content under a retained key is quarantined; preserve the original and examine producer identity/key behavior. Do not rewrite the original record to force acceptance. Replays still retain request receipts and consume inbox byte/batch limits; evaluation_inbox_capacity needs operator review, not unbounded retry.

History unavailable or unsupported filter

Historical queries accept time/source/limit only. Remove unsupported class/status/text filters only if that still answers the authorized question. Confirm archive availability; never replace historical scope with a hot query without telling the reviewer. A narrower hot result is not evidence that no historical event exists.

Rule not enabled or outcome_unknown

Validate the strict stateless subset first. GET /rules reconciles observed state; inspect desired versus observed pipeline state and safe errors. Running is required for enabled. Ambiguous pipeline creation must reconcile its durable intent/name, not blindly create another pipeline. Disable may remain pending until checkpoint stop reaches a terminal state.

409 approval or case conflict

Read the current case and persisted action list. Recheck digest, case_version, workflow_version, policy and expiry. A changed case requires renewed review and preview; never change expected_version merely to force approval. After an unknown HTTP outcome inspect the stored receipt before retry. A repeated matching decision is reconciled; an opposite decision conflicts.

Cost unavailable or query limit

Unconfigured inventory/billing is unavailable, not zero. An invalid snapshot fails explicitly. Narrow time and row bounds after query resource errors; a row limit alone does not guarantee low scan cost. Preserve safe error codes and operation IDs for the operator, with no raw records, credentials or provider identifiers in general diagnostics.