Errors and status codes

Common responses for /api/intel/list and /api/intel/reports.

Status	`error` (typical)	When
200	—	Success (including empty shelf when `configured: false`)
400	`missing_username`	No `username`
400	`invalid_select`	`select` not `all` or `range`
400	`range_requires_from_to_or_ids`	Range without filters
402	Payment challenge body	Paid select, no / bad payment
402	`insufficient_payment`	Settled amount below required
402	settlement failure codes	Facilitator / signature reject
404	`not_found`	Unknown username / 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 can’t settle
502	`intel_*_failed` / `payment_claim_failed`	Upstream / storage failure
503	`intel_kv_not_configured`	Reports path needs KV; misconfigured deploy

A bare 402 without a settled retry is normal — read accepts / extensions, pay, retry with X-402-Payment.

​Errors and status codes