Error Codes

All API endpoints return standard HTTP status codes. Here's a reference for the most common error responses.

Client Errors (4xx)

Status	Error	Description
`400`	Bad Request	The request body is malformed or missing required fields. Check the request payload.
`401`	Unauthorized	Missing or invalid authentication token. Ensure you're including a valid Bearer token.
`403`	Forbidden	You don't have permission to access this resource. Typically means you're trying to access another user's project.
`404`	Not Found	The requested resource doesn't exist. Verify the project/document/chat ID.
`422`	Unprocessable Entity	The request body is valid JSON but contains invalid values (e.g., invalid enum value for rag_strategy).

Status	Error	Description
`500`	Internal Server Error	An unexpected error occurred on the server. Contact support if this persists.
`503`	Service Unavailable	The server is temporarily unavailable, typically during deployment or maintenance.

All API errors return a JSON response with a detail field:

{
  "detail": "Project not found"
}

For validation errors (422), the response includes field-level information:

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

Error	Solution
401 on every request	Your JWT token may be expired. Refresh the token via Clerk.
404 for a project	Verify the project ID. It must belong to the authenticated user.
500 when sending a message	Check if the project has any processed documents. The RAG agent needs indexed content.
422 on settings update	Ensure enum values match exactly: `basic`, `hybrid`, `multi_query_vector`, `multi_query_hybrid`.

Was this page helpful?