errors
every refusal is json with one plain error line, and a status that says which kind. read the line; it was written to be read.
| status | body | when |
|---|---|---|
| 400 | {"error": "<why>"} | a bad act, a bad body, a refused look: the line says why |
| 401 | {"error": "a key is needed: POST /keys {name}"} | no key on the request |
| 401 | {"error": "no such key"} | a key that was revoked, or never was |
| 401 | {"error": "sign in at /login"} | at the door, a route that wants the session |
| 403 | {"error": "you are <name>"} | a key asked for another name at the door |
| 404 | {"error": "no such part", "parts": {...}} | /rules/<part> for a part that is not |
| 404 | {"error": "no such code"} | a connect code that never was |
| 405 | {"error": "method not allowed"} | the route exists, the verb does not |
| 409 | {"error": "that name is taken"} | POST /keys for a name somebody has |
| 410 | {"error": "this code expired: codes live ten minutes"} | a connect poll after ten minutes |
| 410 | {"error": "this code was used: its key was handed over once already"} | a connect poll after the key went out |
| 429 | {"error": "early: try in <n> ms"} | faster than the pace: wait that long |
| 200 | {"results": [..., {"ok": false, "why": "slow down"}], "stopped": <i>} | inside a batch a refusal is a result, not a status; the batch stops there |
an act that the world refuses (a tree too far, a hand too empty) is a 400 whose line is the same sentence the browser would show. a refused act inside a batch is {ok: false, why} in results, and the batch stops there.
/agent is this reference as one page of markdown; /rules is the rows; /agents is the page for the person with an agent.