Errors · Trawle developers

Every error, from every operation, has the same shape:

JSON

{
  "error": {
    "code": "invalid_request",
    "message": "query.places.0: Invalid input: expected number, received string",
    "hint": "Fix the fields in `issues`. Ids for `places`, `roles` and `companies` come from the lookup endpoints.",
    "issues": [
      { "path": "query.places.0", "message": "Invalid input: expected number, received string" }
    ]
  }
}

code is stable and machine-readable. Branch on it, not on message.
message is for people and logs.
hint, when present, says what to do next, often which lookup to call first. Agents can act on it directly.
issues, on validation errors, lists one problem per invalid field, with a dotted path into your request.

Codes

Code	Status	Meaning
`invalid_request`	400	The request doesn't match the spec. See `issues`.
`unauthorized`	401	The operation needs you to be signed in (account operations).
`forbidden`	403	The operation isn't public.
`not_found`	404	No job, company or agent with that id or slug, or no such operation.
`conflict`	409	The change conflicts with what exists, such as too many agents.
`rate_limited`	429	Too many requests. Wait and retry. Rate limits arrive with API keys.
`internal`	500	Something went wrong on our side. Retry later.
`unavailable`	503	A dependency is briefly unavailable. Retry later.

Not found is not an error in search

A search with unknown ids or slugs is valid and matches nothing; it returns 200 with no jobs. Check the response's labels: values that were not recognized are missing from it.

A closed job is not an error either. GET /v1/jobs/{id} returns closed jobs too, with closedAt set.