Errors

HTTP status codes and error response format.

Error format

Errors return JSON with a detail field. Validation errors may return an array of objects.

json

{
  "detail": "Not authenticated"
}

json

{
  "detail": [
    {
      "loc": ["body", "message"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Code	Meaning	Common causes
400	Bad Request	Invalid JSON, missing fields, validation errors
401	Unauthorized	Missing or invalid X-Clerk-User-Id header
403	Forbidden	Disabled knowledge base, access denied
404	Not Found	KB, document, conversation, or key not found
409	Conflict	Document still processing, invalid retry state
422	Validation Error	Request body failed schema validation
429	Rate Limit	KB rate limit exceeded (when configured)
500	Internal Error	Unexpected server error