Agents API
Errors and exit codes
The stable error codes of the Agents API v1 and the exit codes of the krad CLI.
Every refusal is one line:
{"Error":{"code":"not_found","message":"..."}}Codes are stable; messages are for people and may change. Match on code, never on message. A request that runs past its deadline is not an error: the answer is the bare string "TimedOut", and the CLI exits with 3.
Error codes
| Code | Meaning | CLI exit |
|---|---|---|
bad_request | The line or a field is malformed, or a name is ambiguous | 1 |
unavailable | The app stopped serving, dropped the request or the caller left | 2 |
slow_subscriber | A subscriber fell 256 lines behind and was dropped | 2 |
not_found | No such agent, session, Kraddie, automation, run, group, file or memory | 4 |
unauthorized | Wrong token, or a Lead caller without the lead token | 5 |
forbidden | Not allowed for this caller: not a lead, a client, a path outside the group, memory out of reach for reading | 5 |
unsupported | Not possible here: a lead's mailbox, another environment than the one on screen, a caller with no group | 5 |
not_owned | Not one of the lead's Workers, or a session or run outside its group | 5 |
busy | Still working; close with cancel_turn | 5 |
out_of_reach | A Kraddie's memory this chat may not read | 5 |
unsupported_api_version | The app serves another API version | 6 |
failed | The app tried and could not do it | 7 |
worktree_not_clean | A worktree with uncommitted or unmerged work was kept | 7 |
New codes may be added in v1. Treat an unknown code as a refusal you do not understand. See Compatibility.
CLI exit codes
| Exit | Meaning |
|---|---|
| 0 | Done |
| 1 | Wrong arguments |
| 2 | The app cannot be reached; also a stale discovery file, a dropped slow subscriber or a missed heartbeat |
| 3 | Timed out |
| 4 | No such agent, session or file |
| 5 | Refused for this caller |
| 6 | The app speaks another API version |
| 7 | The app could not do it |
krad wait 4 --timeout 900
case $? in
0) krad read 4 --lines 60 ;;
3) echo "still working" ;;
2) echo "the app is not running" ;;
esacRun outside a Krad ADE terminal with no live api.json, the CLI cannot find the app and exits with 2.