> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tolmo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tolmo API Error Responses and Status Codes

> Read the Tolmo API error body, understand what each status code means, and handle retries, precondition failures, and permission errors correctly.

Tolmo signals failure with the HTTP status code. Any response outside the `2xx` range carries a JSON body describing what went wrong.

## Error shape

```json theme={null}
{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Finding not found"
}
```

| Field        | Type   | Description                                                          |
| ------------ | ------ | -------------------------------------------------------------------- |
| `statusCode` | number | The HTTP status code, repeated in the body                           |
| `error`      | string | The status code's reason phrase, for example `Not Found`             |
| `message`    | string | A human-readable explanation of this specific failure                |
| `code`       | string | A machine-readable identifier, present on some errors                |
| `validation` | array  | Present on schema validation failures; one entry per offending field |

Branch on `statusCode`, and on `code` where an endpoint documents one. Treat `message` as text for a human — it is written to be read, and its wording may change.

## Status codes

| Code  | Meaning                                                                                                           | What to do                                                |
| ----- | ----------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| `400` | The request failed validation — a malformed body, an unknown enum value, or a parameter outside its allowed range | Fix the request. Retrying unchanged will fail again       |
| `401` | The token is missing, unrecognized, or expired                                                                    | Re-authenticate. For a user token, run `tolmo auth login` |
| `403` | The token is valid but lacks permission for this operation                                                        | Use a token with the right role. Do not retry             |
| `404` | The resource does not exist — **or** it exists in an organization your token cannot see                           | Check the id and the org slug. See below                  |
| `409` | The request conflicts with the resource's current state, such as an invalid status transition                     | Re-read the resource and reconcile before retrying        |
| `412` | A precondition was not met — a required prior step has not completed                                              | Satisfy the precondition, then retry                      |
| `503` | A dependency Tolmo relies on is unavailable                                                                       | Retry with backoff                                        |

### `404` versus `403`

Tolmo returns `404` rather than `403` for a resource in an organization your token cannot access. This is deliberate: a `403` would confirm that the resource exists, which leaks information across organization boundaries.

So a `404` means one of two things, and the API will not tell you which:

* the id is wrong, or
* the resource belongs to an organization you cannot see.

Check the org slug in your path before assuming the id is bad.

Within an organization you *can* see, `403` behaves normally — it means your role is insufficient for this operation. Creating a finding as a *published* one with an ordinary member token returns `403`; creating it as a draft succeeds.

## Retrying

Retry `503`, and `429` if you receive one, with exponential backoff.

Do not blindly retry `400`, `401`, `403`, or `404` — none of them will succeed on a second identical attempt.

Writes are not automatically idempotent. If a write times out and you cannot tell whether it landed, re-read the resource before sending it again rather than risking a duplicate.

## Validation errors

Request validation runs from the same schemas that generate this reference, so a `400` almost always means the request disagrees with a documented parameter or body schema.

Validation failures carry an extra `validation` array alongside the usual fields — one entry per offending field, so you can report every problem at once instead of fixing them one request at a time:

```json theme={null}
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "...",
  "validation": [
    {
      "keyword": "too_big",
      "instancePath": "/limit",
      "schemaPath": "#/limit/too_big",
      "message": "Too big: expected number to be <=100",
      "params": { "origin": "number", "maximum": 100, "inclusive": true }
    }
  ]
}
```

`instancePath` points at the field, `keyword` is the validation rule it broke, and `params` carries that rule's bounds. Check the endpoint's parameter table for each field's type and limits.