Errors

One error shape, a stable code, and what to do about each type.

Every non-2xx response has the same body:

{
  "error": {
    "type": "invalid_request_error",
    "code": "validation_failed",
    "message": "email is not a valid address.",
    "param": "email",
    "detail": [
      { "field": "email", "message": "value is not a valid email address", "code": "value_error" }
    ],
    "request_id": "req_8f2c...",
    "documentation_url": "https://docs.chatsailer.com/guides/errors"
  }
}

Branch on type for control flow and on code for specific handling. Both are stable; message is written for humans and may be reworded.

Always log request_id. It is echoed in the X-Request-ID response header, and quoting it lets us find your exact request.

Types

Type	HTTP	What it means	What to do
invalid_request_error	400, 422	The request is malformed or fails validation	Fix the request. Read detail for the offending fields. Do not retry unchanged
authentication_error	401	Missing, malformed, revoked, or expired token	Check the Authorization header. Do not retry unchanged
permission_error	403	Authenticated, but not allowed	Usually a missing scope, or a workspace write policy. See below
not_found_error	404	No such record, or it is outside your workspace	Do not retry
conflict_error	409	Conflicts with existing state, e.g. a duplicate	Reconcile, then retry
rate_limit_error	429	Too many requests	Back off and retry — see below
api_error	5xx	Something broke on our side	Retry with backoff. If it persists, send us the request_id

A 404 does not distinguish “does not exist” from “belongs to another workspace”. That is deliberate: telling them apart would let anyone probe for record ids across workspaces.

Missing scopes

A 403 from a scope check names exactly what is missing, so you do not have to guess:

{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This endpoint requires the contacts:write scope."
  }
}

A 403 that is not insufficient_scope usually means workspace write policy — for example, an entity mirrored from an external CRM. Call GET /v1/capabilities to see which entities you may write.

Retrying

Retry rate_limit_error and api_error. Do not retry 4xx errors unchanged; they will fail identically.

for attempt in range(5):
    response = httpx.request(method, url, headers=headers, json=body)
    if response.status_code < 400:
        return response.json()
    if response.status_code not in (429, 500, 502, 503, 504):
        raise SailerError(response.json()["error"])
    time.sleep(2 ** attempt)

Use exponential backoff with jitter. Retrying immediately during a rate limit extends it.