Errors and exit codes
Exit codes are part of the contract, and every error body says whether to retry.
Exit codes
Stable, and part of the contract — a caller in CI must be able to tell these apart without parsing prose.
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Runtime failure (network, server error) |
| 2 | Usage error (unknown command, missing argument) |
| 3 | Not signed in, or the credential was rejected |
| 4 | Resource not found |
| 5 | Out of credit, or rate limited |
| 6 | An eval suite regressed |
3 is how a script checks before assuming it can act:
speko-cli whoami >/dev/null 2>&1 || { echo "run: speko-cli login"; exit 1; }Explaining a code
speko-cli explain INSUFFICIENT_CREDITSNeeds no credential — the catalogue is public, so explaining UNAUTHORIZED does
not fail with the error it is explaining.
Most codes carry only a category so far. Where no explanation has been written, it says so rather than inventing one.
Error bodies
Every error response carries:
| Field | |
|---|---|
code | Stable identifier, e.g. INSUFFICIENT_CREDITS |
retryable | Whether retrying could possibly help. Branch on this. |
docs_url | Where the code is documented |
hint | What to do about it, where one has been written |
Before debugging a failing call
speko-cli doctorReports credit, provider reachability, the scopes this session holds, and the last failed session. It exits non-zero only when something found will actually stop a call from working, so it is usable as a precondition in a script.
It states facts rather than verdicts: it names the provider that needs a key instead of reporting that routing failed, and points at the last failed session without guessing its cause.