Skip to content
Build with Mammoth: open the docs menu

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.

  • verify is the CLI's own verdict: verified (true or false), a state, any warnings, a reason when it is not verified, and needs_user. When needs_user is set, stop and tell a person before the next step. A row-changing step also carries rows_before and rows_after.
  • outcome is settled, pending, partial or failed. The envelope's top-level status follows the last three: partial exits 3, and failed exits 1 even though the API call itself went through (verify.reported_status keeps the earlier word).
  • A write still running when the wait ends reports status: pending and verify.next_command (mammoth view pipeline wait VIEW_ID, or mammoth job wait ID for an automation). It exits 0: the change was accepted, so wait on it and never replay it.
  • state is a fresh read of what the write produced, taken after it settled, not echoed from your request. If that read fails, state says unreadable and verify.verified becomes 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

CodeMeaningRetry?
0Successn/a
1API errorno
2Usage, input, or confirmation failureno
3Partial: a write whose read-back shows only part of it took effectno
4Authentication failureno
5Not foundno
6Conflict, including file_exists when an export would overwrite a local fileno
7Retryable (network or timeout)yes
130Interruptedno

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.

StatusWhen
304A GET sent If-None-Match with the current ETag. There is no body: keep your copy. See conditional requests.
413The request body is too big: over 50 MiB for a file upload, over 10,000,000 bytes for most other requests.
500An 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_codeStatusMeaning
4RESO003401The token is invalid or revoked. Check it; do not retry.
4OAUT008401The token has expired. Create a new one, or refresh an OAuth token.
4GENR007400VALIDATION_ERROR: a parameter or body field is missing or out of range. details says which.
4GENR012403"Cannot access this API with API-tokens". The route is for a signed-in person only, such as managing API tokens.
4GENR034403"This connection is read-only: it can read data but not change it". A read-only connection tried to write.
4JOBS002404"Job not found for given id". The job does not exist. A job someone else started answers 400 with 4PERM002.
5GENR011400NOT_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.

MethodRequests per minute
GET600
POST300
PATCH60
DELETE60
PUT and any other method600

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

Report an issue · support@mammoth.io