From 8e441ead9395b55c8e7990f7d48e77891d124422 Mon Sep 17 00:00:00 2001 From: iris Date: Sat, 4 Jul 2026 13:38:26 +0200 Subject: [PATCH] docs(agent-ui): document HTTP error codes for POST endpoints MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit After the fix in c708f698, POSTs no longer always return 200 — they use semantic status codes: 400 for bad input, 409 for retryable state conflicts (turn in flight, hive-c0re busy), 500 only for genuine failures. Update the preamble to the Per-agent endpoints section to reflect this. --- docs/web-ui/agent.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/docs/web-ui/agent.md b/docs/web-ui/agent.md index 6b1542c7..bf0a62e3 100644 --- a/docs/web-ui/agent.md +++ b/docs/web-ui/agent.md @@ -277,9 +277,14 @@ Unknown `/foo` shows an error row instead of being silently sent. ## Per-agent endpoints -All POSTs return 200 (no 303 redirects). The matching mutations -fire `LiveEvent` variants on the per-agent bus, so the client -doesn't refetch `/api/state` on submit — the SSE stream +Successful POSTs return 200 (no 303 redirects). Error responses +use semantic status codes: **400** for missing/invalid input +(`body` required, unknown model name, invalid effort level), +**409** for retryable state conflicts (turn in flight when +`/compact` is called, hive-c0re busy on `/api/state`), +**500** only for genuine server/transport failures. The matching +mutations fire `LiveEvent` variants on the per-agent bus, so the +client doesn't refetch `/api/state` on submit — the SSE stream delivers the new state faster anyway. Only the login flow still polls (session output streams in updates that aren't event- shaped).