Errors & Pagination

The error body shape, HTTP status conventions, and how list endpoints paginate

Error shape

This is a FastAPI service, so most errors come back as a plain JSON object:

{
  "detail": "Missing a CRM read scope"
}

detail is usually a human-readable string. The one exception is 422 Unprocessable Entity — a request-body/query validation failure raised by FastAPI itself before your handler ever runs — where detail is an array of per-field problems instead:

{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "name"],
      "msg": "Field required",
      "input": {}
    }
  ]
}

Status codes you’ll see across this API

Status	Meaning
400 Bad Request	Malformed input the handler validated itself (invalid enum value, no active organization on the token, unknown filter)
401 Unauthorized	Missing/expired/invalid bearer token — see Authentication
403 Forbidden	Valid token, insufficient scope
404 Not Found	The resource doesn’t exist, or exists in a different organization than the token’s (row-level security makes the two indistinguishable by design — a cross-org read looks exactly like a missing row, never a 403 that would confirm the row exists)
409 Conflict	A uniqueness/state constraint (duplicate tag name, non-empty folder without cascade=true)
422 Unprocessable Entity	Request body/query failed Pydantic validation
502 Bad Gateway	The backend’s own call to the database (PostgREST) or another upstream failed
503 Service Unavailable	A dependent feature isn’t available in this deployment (e.g. report rendering, which needs the render-worker image)

Pagination

List endpoints take limit and offset query parameters. There’s no single envelope shared across every resource — it varies by endpoint, so check the specific page:

• Header-based: some list endpoints (e.g. GET /contacts) return a bare JSON array and put the total match count (ignoring limit/offset) in the X-Total-Count response header, so you can compute total pages without a second request.
• Body-based: others (e.g. GET /files/list) wrap the array in an object alongside the pagination params you sent: {"files": [...], "limit": 50, "offset": 0}.
• Bare array, no total: others (e.g. GET /deals) just return the page as a JSON array with no total-count signal at all — keep incrementing offset until you get back fewer rows than limit.

Each endpoint in the Core CRM API reference states which shape it uses. limit defaults and caps also vary per endpoint (commonly defaulting to 50–200 and capped at 200–500 server-side regardless of what you pass) — again, see the specific endpoint.