Mammoth errors and exit codes
How failures are reported, which of them are worth retrying, and which are a bug in the request.
Read the envelope, not the text
In machine output the CLI writes a versioned envelope. Success goes to stdout; errors go to stderr. Branch on the exit code and the stable error.code, never on the human-readable message.
Success, stdout:
{"schema_version": 1, "data": "<result>", "meta": {"command": "…", "profile": "default", "workspace_id": 4, "project_id": 180}}
meta carries only the keys that have a value. It adds pagination on a paged read, and update_available ({"current", "latest", "command"}) when a newer CLI release exists. The CLI checks once a day, after a command, and never blocks on it. It installs a newer release by itself only in an interactive terminal; in CI, in a pipe or in an agent run it only reports update_available. MAMMOTH_AUTO_UPGRADE=1 forces the install on, and MAMMOTH_NO_UPDATE_CHECK=1 turns the check off.
A write returns what it did
Every command that changes something adds two blocks to data. Read them before you build on the change.
verifyis the CLI's own verdict:verified(true or false), astate, anywarnings, areasonwhen it is not verified, andneeds_user. Whenneeds_useris set, stop and tell a person before the next step. A row-changing step also carriesrows_beforeandrows_after.outcomeissettled,pending,partialorfailed. The envelope's top-levelstatusfollows the last three:partialexits 3, andfailedexits 1 even though the API call itself went through (verify.reported_statuskeeps the earlier word).- A write still running when the wait ends reports
status: pendingandverify.next_command(mammoth view pipeline wait VIEW_ID, ormammoth job wait IDfor an automation). It exits 0: the change was accepted, so wait on it and never replay it. stateis a fresh read of what the write produced, taken after it settled, not echoed from your request. If that read fails,statesaysunreadableandverify.verifiedbecomes false.
A success envelope proves the call went through. The state block shows the outcome.
Error, stderr:
{"schema_version": 1, "error": {"code": "…", "message": "…", "summary": "…", "hint": "…", "details": {}, "request_id": null, "retryable": false, "authorization_required": false, "recovery_commands": ["…"], "log_ref": {"file": "…", "run_id": "…"}}}
summary is a plain-language sentence you can show a person. log_ref points at the local run log: mammoth log tail --input '{"run_id": "RUN_ID"}' lists every request that run made, with its HTTP status and the backend request_id. Quote both when you report a backend fault.
schema_version is a compatibility contract. It is 1 today and increments only on a breaking change to the envelope shape. Check it if you parse envelopes across CLI upgrades.
Exit codes
| Code | Meaning | Retry? |
|---|---|---|
| 0 | Success | n/a |
| 1 | API error | no |
| 2 | Usage, input, or confirmation failure | no |
| 3 | Partial: a write whose read-back shows only part of it took effect | no |
| 4 | Authentication failure | no |
| 5 | Not found | no |
| 6 | Conflict, including file_exists when an export would overwrite a local file | no |
| 7 | Retryable (network or timeout) | yes |
| 130 | Interrupted | no |
A timeout, exit code 7 or an interruption does not prove a write failed. When details.operation_state is outcome_unknown, the change may have committed: reconcile it with mammoth job get or a read of the resource before you replay it.
Exit 3 is not a transport failure. Read verify to see which part of the write took effect, finish or undo it, and do not replay the whole command.
Commands the server does not offer yet
schedule create fails at once with the error code feature_unavailable (exit 2) and sends no request. It does not appear in mammoth schema find. Its hint points to the two routes that work: append each new file with mammoth file upload FILE --input '{"append_to_ds_id": DATASET_ID}', or connect a cloud source and schedule its refresh with mammoth automation create.
Local checks
view transform extract-date, date-diff, increment-date and math check column types before any request. A TEXT column is refused with column_type_mismatch, and the error names the convert-type command to run first. An unexpected fault in the CLI itself is reported as internal_error; rerun with --debug for the stack trace.
A command that writes a local file (view export csv, dashboard bi-export, explore-panel export-image, support template export) refuses an existing file with file_exists (exit 6) unless you pass --overwrite.
Confirmation failures
A mutation that needs a confirmation and does not get one fails with exit code 2 and an error code of confirmation_required or confirmation_target_mismatch. It never proceeds and never prompts off a terminal. The rule is the same everywhere: an action that cannot be undone needs --yes, and a confirm_target command also needs --confirm ID with the exact target id. The CLI checks --confirm before it makes any API call.
On the HTTP side
Calling the API directly, a bad or missing credential returns 401; an authenticated caller without permission gets 403. The Python SDK raises MammothAuthError for the first and MammothAPIError for the rest.
The error body
Almost every error is one JSON object at the top level of the response:
{
"error_code": "4RESO003",
"name": "AUTHENTICATION_ERROR",
"message": "Invalid token",
"details": {"error_object": {"code": 12, "message": "Token is invalid"}, "status_code": 401}
}
That is the body the API returns today for a request with a bad token. details and a link appear only when the error has them. A request that fails validation returns 400 with "error_code": "4GENR007" and "name": "VALIDATION_ERROR", and its details lists what was wrong.
Branch on error_code, which is stable, and show message to a person. A few routes answer a 404 or an unexpected 400 in the web framework's own shape, {"status_code", "detail", "extra"}, so a client should fall back to the HTTP status when error_code is missing. A 429 has its own body, below.
Successful responses return the resource directly, with no wrapper. The {data, meta} envelope belongs to the CLI, not to the API.
The status codes you will meet are 202 (an asynchronous job), 304, 400, 401, 403, 404, 409, 410, 413, 422, 429 and 500. A 409 usually means you tried to delete something that is still referenced, such as a parameter or a snippet; show the user the message. The OpenAPI document lists the codes each operation declares; see the REST reference for how to fetch it.
| Status | When |
|---|---|
304 | A GET sent If-None-Match with the current ETag. There is no body: keep your copy. See conditional requests. |
413 | The request body is too big: over 50 MiB for a file upload, over 10,000,000 bytes for most other requests. |
500 | An unexpected server fault. The body is a bare JSON string, "Internal error has occurred. Please reach out to support at support@mammoth.io", not the error object. |
Error codes worth handling
error_code | Status | Meaning |
|---|---|---|
4RESO003 | 401 | The token is invalid or revoked. Check it; do not retry. |
4OAUT008 | 401 | The token has expired. Create a new one, or refresh an OAuth token. |
4GENR007 | 400 | VALIDATION_ERROR: a parameter or body field is missing or out of range. details says which. |
4GENR012 | 403 | "Cannot access this API with API-tokens". The route is for a signed-in person only, such as managing API tokens. |
4GENR034 | 403 | "This connection is read-only: it can read data but not change it". A read-only connection tried to write. |
4JOBS002 | 404 | "Job not found for given id". The job does not exist. A job someone else started answers 400 with 4PERM002. |
5GENR011 | 400 | NOT_IMPLEMENTED: the operation exists in the reference but is not implemented, such as listing a project's schedules. |
Rate limits
Limits are per HTTP method and they apply to every caller, not only to paid tiers.
| Method | Requests per minute |
|---|---|
GET | 600 |
POST | 300 |
PATCH | 60 |
DELETE | 60 |
PUT and any other method | 600 |
A fixed one-minute window, counted in Redis, keyed on your session when authenticated and on the caller IP when not. That last detail matters if you are embedding: anonymous dashboard viewers share a limit by IP.
When you get 429
Over the limit, the API answers 429 with a Retry-After header, in seconds, and this body:
HTTP/2 429
Retry-After: 60
{"message": "Rate limit exceeded."}
Wait for the number of seconds in Retry-After, then retry the same request. Every operation in the OpenAPI document declares this 429, so a generated client can handle it. The Python SDK retries a read that gets 429 twice by itself, but waits at most 5 seconds, so a 429 can still reach your code; curl and other clients get no retry at all.
while : ; do
STATUS=$(curl -sS -o body.json -D headers.txt -w '%{http_code}' "$URL" \
-H "Authorization: Bearer $MAMMOTH_API_TOKEN")
[ "$STATUS" != "429" ] && break
WAIT=$(grep -i '^retry-after:' headers.txt | tr -dc '0-9')
sleep "${WAIT:-60}"
done
Retry a write on 429 only: a 429 is refused before the request runs, so the write did not happen. Never retry a write on a timeout or a 5xx without first reading whether it took effect.
Next up
- Agents and CI: the reliable operation loop, end to end.
- Blast radius and safety: what each command will demand before it runs.