vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

docs(agent-ui): document HTTP error codes for POST endpoints

Browse source 
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.
This commit is contained in:
iris 2026-07-04 13:38:26 +02:00 • committed by mara
commit 8e441ead93
1 changed files with 8 additions and 3 deletions
Download patch file Download diff file Expand all files Collapse all files

11
docs/web-ui/agent.md
View file

@ -277,9 +277,14 @@ Unknown `/foo` shows an error row instead of being silently sent.
## Per-agent endpoints ## Per-agent endpoints
All POSTs return 200 (no 303 redirects). The matching mutations Successful POSTs return 200 (no 303 redirects). Error responses
fire `LiveEvent` variants on the per-agent bus, so the client use semantic status codes: **400** for missing/invalid input
doesn't refetch `/api/state` on submit — the SSE stream (`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 delivers the new state faster anyway. Only the login flow still
polls (session output streams in updates that aren't event- polls (session output streams in updates that aren't event-
shaped). shaped).