Erros

Toda resposta de erro da API usa o status HTTP adequado e retorna um corpo JSON consistente. Independente do tipo de erro, o corpo sempre tem dois campos: error e code.

Formato

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

Campo	Tipo	Descrição
`error`	string	Mensagem legível descrevendo o erro (sempre em inglês).
`code`	string	Código estável e legível por máquina. Use este campo na sua lógica de tratamento de erros.

Códigos de erro

`code`	Status HTTP típico	Quando acontece
`invalid_request`	400	Corpo malformado, campos ausentes ou inválidos, ou ID que não é UUID.
`unauthorized`	401	Token ausente, inválido ou revogado. Veja Autenticação.
`forbidden`	403	O token não tem permissão para acessar aquele recurso.
`not_found`	404	Recurso não existe ou pertence a outra organização.
`conflict`	409	A operação conflita com o estado atual — por exemplo, tentar editar um item de base com `source='file'` ou um item que está em processamento.
`rate_limited`	429	Limite de requisições excedido.
`internal_error`	500	Erro inesperado no servidor.

Status HTTP

A API retorna os seguintes status HTTP:

Status	Significado
`200 OK`	Requisição bem-sucedida com corpo de resposta.
`201 Created`	Recurso criado com sucesso.
`202 Accepted`	Requisição aceita e processando de forma assíncrona.
`204 No Content`	Requisição bem-sucedida sem corpo de resposta (ex.: exclusão).
`400 Bad Request`	Dados da requisição inválidos ou malformados.
`401 Unauthorized`	Token ausente ou inválido.
`403 Forbidden`	Token válido, mas sem permissão para o recurso.
`404 Not Found`	Recurso não encontrado.
`408 Request Timeout`	Timeout no chat síncrono — o agente não respondeu a tempo.
`409 Conflict`	Estado atual do recurso impede a operação.
`429 Too Many Requests`	Limite de requisições excedido.
`500 Internal Server Error`	Erro inesperado no servidor.