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).