Errors and status codes - Xintel

Status codes and error values for the agent routes. A 402 on the first paid request is expected — read the challenge, settle, and retry.

`GET /api/intel/reports`

Status	`error`	Condition
200	—	Menu, or paid/secret bodies
400	`missing_username`	No `username`
400	`missing_select` / `invalid_select`	`select` empty or not `all`/`range`
400	`range_requires_from_to_or_ids`	`range` with no `from`, `to`, or `ids`
402	(challenge body)	Paid select, no payment yet — expected
402	`insufficient_payment`	Settled amount below required
402	`settlement_failed` (or a facilitator error reason)	Payment rejected by the facilitator (e.g. bad signature, expired authorization)
404	`not_found`	Unknown handle / no bundle
404	`no_matching_reports`	`range` matched zero reports
405	`method_not_allowed`	Non-`GET`
409	`payment_already_used`	Payment id already claimed
501	`facilitator_not_configured` / `agent_test_mode_disabled`	Server cannot settle — the deployment has no CDP facilitator credentials (and dev test mode is off). Not something an agent can fix; the operator must configure settlement.
502	`intel_reports_read_failed` / `intel_reports_serve_failed` / `payment_claim_failed`	Upstream or storage failure
503	`intel_kv_not_configured`	Reports path needs KV; deploy misconfigured

`GET /api/intel/list`

Status	`error`	Condition
200	—	Success (including `configured: false` when KV is absent)
405	`method_not_allowed`	Non-`GET`
502	`intel_index_failed`	Index read failure

`GET/PUT /api/intel/bundle`

Not part of the paid API, but returns these:

Status	`error`	Condition
401	`unauthorized`	No first-party authorization
413	`invalid_bundle` (`payload_too_large`)	PUT body over the size cap

A bare 402 with no settled retry is the normal payment handshake, not an error. Read accepts and extensions, pay, then retry with X-402-Payment.