Tolmo API Error Responses and Status Codes

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

Error shape

{
  "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:

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

Getting started

Findings

Queries

Inventory

Integrations

Tolmo API Error Responses and Status Codes

Error shape

Status codes

`404` versus `403`

Retrying

Validation errors

​Error shape

​Status codes

​404 versus 403

​Retrying

​Validation errors

Error shape

Status codes

`404` versus `403`

Retrying

Validation errors