> ## 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. Most API errors return a JSON body describing what went wrong. Some endpoints and provider proxies use a different error shape; check the HTTP status and the endpoint schema.

## 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 the HTTP response status, 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, or the `{orgSlug}` in the path is not the token's organization | Check the org slug, or 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`

An API key is bound to one organization. Using it against any other `{orgSlug}` is rejected with `403`, regardless of what that slug is — check that the slug in your path is your own.

Inside your own organization, a `404` on a resource id means one of two things, and the API will not tell you which:

* the id is wrong, or
* the resource belongs to another organization.

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

Within an organization you *can* see, `403` also 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.