Errors

Every error response from the API uses the appropriate HTTP status and returns a consistent JSON body. Regardless of the error type, the body always contains two fields: error and code.

Format

{
  "error": "Invalid or missing API token",
  "code": "unauthorized"
}

Field	Type	Description
`error`	string	Human-readable message describing the error (always in English).
`code`	string	Stable, machine-readable code. Use this field in your error-handling logic.

Error codes

`code`	Typical HTTP status	When it happens
`invalid_request`	400	Malformed body, missing or invalid fields, or an ID that is not a valid UUID.
`unauthorized`	401	Missing, invalid, or revoked token. See Authentication.
`forbidden`	403	The token does not have access to that resource.
`not_found`	404	Resource does not exist or belongs to another organization.
`conflict`	409	The operation conflicts with the current state — for example, editing a knowledge-base item with `source='file'`, or an item that is currently being processed.
`rate_limited`	429	Request rate limit exceeded.
`internal_error`	500	Unexpected server-side error.

HTTP statuses

The API returns the following HTTP statuses:

Status	Meaning
`200 OK`	Successful request with a response body.
`201 Created`	Resource created successfully.
`202 Accepted`	Request accepted and processing asynchronously.
`204 No Content`	Successful request with no response body (e.g. deletion).
`400 Bad Request`	Invalid or malformed request data.
`401 Unauthorized`	Missing or invalid token.
`403 Forbidden`	Valid token, but no permission for that resource.
`404 Not Found`	Resource not found.
`408 Request Timeout`	Timeout on synchronous chat — the agent did not respond in time.
`409 Conflict`	Current resource state prevents the operation.
`429 Too Many Requests`	Rate limit exceeded.
`500 Internal Server Error`	Unexpected server-side error.