> AI agents: this is one page from Mammoth Analytics documentation. The index of all pages as Markdown is https://mammoth.io/docs/llms.txt. Append `.md` to any docs URL, or send `Accept: text/markdown`, to get Markdown.

# Mammoth errors and exit codes

> The REST error body, the CLI error envelope and exit codes, which failures are worth retrying, per-method rate limits, and how to handle 429.

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:**

```json
{"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:**

```json
{"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 |

> **Never retry a mutation on anything but 7**
>
> The CLI does not retry a mutation without a real server idempotency contract, and neither should your code. An interruption returns `130` and closes sessions and files cleanly.

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:

```json
{
  "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.

> **One letter apart, two different contracts**
>
> The API error uses `error_code` at the top level. The CLI envelope uses `error.code`. A client that reads the wrong one silently finds nothing.

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](https://mammoth.io/docs/build/#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](https://mammoth.io/docs/build/#conditional-requests-with-etags). |
| `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.

```bash
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.

> **There is no daily quota**
>
> Not for any tier. The one-minute window above is the only limit that exists. If you have designed against a daily request allowance, it was never real.

## Next up

- [Agents and CI](https://mammoth.io/docs/agents/ci/): the reliable operation loop, end to end.
- [Blast radius and safety](https://mammoth.io/docs/agents/safety/): what each command will demand before it runs.

---
Source: https://mammoth.io/docs/build/errors.md · Updated: 2026-11-02
