Skip to main content
Every command returns one of these, and the set is stable within a major version, so case $? is safe to write against. Code 10 is reserved and is never returned today.

Distinctions that matter in scripts

3 is never worth retrying. A rejected credential will not be accepted a moment later, and repeating it is how an address gets blocked. Fix the key instead. 9 and 124 answer different questions. 9 means the network failed. 124 means the time you allowed ran out, whether through --timeout or --exit-timeout. A job that retries on 9 and gives up on 124 is usually behaving correctly. Two 403 responses map to 5. scheduling_not_included means the plan does not include scheduled sends. browser_not_allowed means the client configuration is wrong. Both are reported as preconditions rather than auth failures: the credential was valid, and the entitlement was not. Nothing retries by itself. When the server asks for a wait, that is reported and the decision is left to whatever is running the command. A retry after 7 or 8 is only safe with an idempotency key.

Failure and stdout

On failure stdout is empty, so piping into a parser never yields half a document. In JSON mode an error is written to stderr in a consistent shape:
mailkube doctor is the single exception. It exits 5 when a check failed, having written the whole report anyway: the code is a verdict on the report rather than a failure to produce one. That is what makes mailkube doctor && ./deploy.sh stop at a broken configuration while still telling you which check broke.

Looking up an error

Every entry carries the HTTP status, whether it is worth retrying, a summary, one or more actions to take, and sometimes a note. It knows 30 API error names and 14 SMTP replies, including code-plus-status pairs such as 550 5.6.0, so mailkube errors explain 550 works the same way:
That dumps the whole catalog as JSON. Grep it when you have a name in front of you and no idea where it came from.

Where each error is documented

The CLI’s catalog is a lookup for what you have in front of you. The authoritative descriptions live with the surface that produces them:
  • API errors for every name the REST API returns, with its status code and cause.
  • SMTP error codes for what a submission server’s reply means.
  • Rate limits for what triggers a 7 and how long to wait.

Branching in a script

See Scripting for the stream contract and the output formats.