Errors
A failed response has "ok": false and an error object with a code from the closed set below
and a human-readable message of at most 256 bytes. Each code comes with a fixed set of HTTP
statuses; a client that sees any other pairing should treat the response as invalid. This table is
checked against internal/protocolv2 when the docs build.
| Code | HTTP status | Meaning | What to do |
|---|---|---|---|
invalid_request |
400, 405, 413, 415 | The request was malformed: not POST, not JSON, too large, an unknown or missing field, a bad value. | Fix the request. Nothing ran. |
forbidden |
403 | The caller’s uid is not an operator (or a reader, for read-only operations), or the lease token is missing, wrong or no longer current (“valid holder capability required”). | Use an authorized account; for a token, check status and use the current holder’s token. |
not_found |
404 | Unknown endpoint, or no such bench or workspace. | Check the path and key. |
conflict |
409 | The current state refuses the operation, or a request ID was reused with a different body. | Read status; reuse an ID only with its original body. |
in_progress |
409 | The same request is still running. | Wait, then retry with the same ID and body. |
operation_in_doubt |
409, 503 | The daemon cannot tell whether an earlier attempt took effect, for example after a restart. It is never run again automatically. | Reconcile by hand: inspect status, stop the recorded execution, checkpoint and release. A new ID is not reconciliation. |
unavailable |
503 | The service is shutting down, at its connection or active-operation limit, its receipt budget is exhausted, a complete result would not fit, or the operation was cancelled or hit a deadline such as the mirror timeout. | Inspect status and the retained state first; then retry with the same request ID, or query one key. |
operation_failed |
422 | The operation ran and failed, for example a nonzero command exit or a refused checkpoint. A retained grant may come with it. | Inspect the retained workspace state. |
capacity_exhausted |
422 | A fixed quota reservation cannot fit. The v2 refusal reports the needed and total byte and inode budgets. Only /v2/operations returns it. |
Free capacity or request less. Limits are never raised to fit. |
When the receipt store is full, new growth operations are refused, but stop, checkpoint,
release and archive stay available so work can always be reconciled.
The CLI
Section titled “The CLI”The bench CLI prints the response envelope and exits nonzero on an error. For run, a nonzero
command exit status propagates through the CLI once fencing completed. Without --socket, direct
local commands print the engine’s own JSON and report errors on stderr as bench: <message>.