Erros

Use primeiro o status HTTP para classificar a falha e, quando ele existir, o campo code para decidir a ação específica. Não programe contra o texto de error: ele é escrito em inglês, pode mudar e, em algumas falhas internas, pode conter detalhes técnicos.

Formato canônico

Os endpoints de Agentes, Bases, Conversas, Listas e Tags usam este envelope:

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

Campo	Tipo	Como usar
error	string	Mensagem em inglês para diagnóstico. Não a use como identificador nem a mostre diretamente ao cliente final.
code	string	Identificador legível por máquina. Trate os códigos conhecidos e mantenha um fallback para valores novos ou ausentes.

Cuidado

O endpoint de Chat ainda possui respostas legadas fora desse envelope. Seu parser precisa aceitar code ausente ou desconhecido e nunca deve rejeitar a resposta inteira por causa disso. Veja Exceções atuais do Chat.

Códigos canônicos atuais

code	Status típico	O que significa	Ação recomendada
invalid_request	400	JSON, parâmetro, campo ou UUID inválido.	Corrija a requisição; repetir o mesmo conteúdo não ajuda.
unauthorized	401	Token ausente, inválido ou revogado.	Interrompa a chamada e substitua o token. Veja Autenticação.
forbidden	403	O alvo não pertence à organização ou não é uma caixa API compatível.	Revise o recurso e a configuração; não repita automaticamente.
not_found	404	Recurso ou rota não encontrado, inclusive quando pertence a outra organização.	Confirme o ID e o caminho. Um método não suportado também cai em 404, não em 405.
conflict	409	O estado atual impede a operação, como descadastro preservado, tag duplicada ou item de base não editável.	Leia o estado atual e reconcilie antes de tentar outra ação.
internal_error	500	Falha inesperada de aplicação, banco ou configuração.	Considere o resultado desconhecido; reconcilie e só então repita com backoff.
service_unavailable	503	Uma dependência da busca da base está indisponível.	Repita com backoff exponencial e jitter; não interprete a resposta como base sem resultados.

Nota

rate_limited existe no tipo interno e no schema OpenAPI, mas nenhuma rota pública atual devolve 429 ou define Retry-After. Trate o código como reservado, não como um limite ativo documentado. Se ele aparecer no futuro, respeite o status e qualquer Retry-After recebido.

Status HTTP emitidos hoje

Status	Uso atual
200 OK	Leitura, atualização, ação concluída ou Chat síncrono.
201 Created	Item de base criado ou associação de lista criada/confirmada.
202 Accepted	Chat aceito para processamento assíncrono ou colocado na fila de debounce. A resposta não prova que a execução terminou.
204 No Content	Item de base excluído; não tente decodificar JSON.
400 Bad Request	Entrada inválida.
401 Unauthorized	Token ausente ou inválido.
403 Forbidden	Alvo do Chat proibido, incompatível ou inativo.
404 Not Found	Recurso, rota ou combinação de método e rota não encontrada.
409 Conflict	Estado atual incompatível com a operação.
500 Internal Server Error	Falha inesperada ou falha do pipeline síncrono do Chat.
503 Service Unavailable	Dependência temporariamente indisponível ou falha de persistência classificada pelo pipeline.

A API não implementa hoje respostas públicas 408 Request Timeout ou 429 Too Many Requests. No Chat síncrono não existe um prazo HTTP fixo do produto: um timeout de modelo ou outra falha de pipeline chega atualmente como 500, enquanto um proxy ou cliente pode encerrar a conexão sem receber JSON. Consulte o contrato completo em Chat.

Exceções atuais do Chat

O Chat compartilha parte do runtime dos outros canais e ainda não respeita um catálogo fechado de códigos. Dependendo da fase, você pode receber:

• códigos minúsculos específicos, como agent_not_found e trigger_inactive;
• códigos legados em maiúsculas, como AGENT_NOT_FOUND, AGENT_ARCHIVED e AGENT_INACTIVE;
• a classe técnica da falha, como TimeoutError, em um 500;
• em um caminho defensivo raro, um 500 com error, mas sem code.

Essa divergência está registrada como BUG-API-038; a promessa de 408 e o catálogo incompleto do Swagger também estendem BUG-API-022. Até o produto unificar o contrato, use o status como fallback e registre códigos desconhecidos para observabilidade, sem falhar ao decodificá-los.

Cuidado

Uma exceção não tratada numa rota CRUD pode devolver a mensagem original do backend dentro de error. Isso está registrado como BUG-API-037. Não exiba esse texto diretamente, não o use como regra de negócio e evite persistir detalhes desnecessários em logs acessíveis ao cliente.

Estratégia de tratamento

1. Leia o corpo como texto e tente decodificar JSON; proxies também podem devolver HTML ou corpo vazio.
2. Se a resposta for 2xx, trate cada status conforme o endpoint — em especial 202 e 204.
3. Em 400, 401, 403, 404 ou 409, corrija entrada, credencial, alvo ou estado antes de repetir.
4. Em 500 ou 503, considere que uma escrita pode ter acontecido parcialmente. Consulte o recurso ou histórico antes do retry.
5. Quando o retry for seguro, use backoff exponencial com jitter e um limite de tentativas. Não há header Retry-After garantido hoje.

const response = await fetch(url, options);
const raw = await response.text();

let body = null;
try {
  body = raw ? JSON.parse(raw) : null;
} catch {
  // Corpo não JSON vindo do proxy ou da plataforma.
}

if (!response.ok) {
  const code = typeof body?.code === "string" ? body.code : null;

  if (code === "unauthorized") rotateOrReplaceToken();
  else if (response.status >= 500) scheduleReconciliationAndRetry();
  else handlePermanentFailure(response.status, code);
}

Dica

Depois de uma falha de rede ou 5xx, não presuma que “nada aconteceu”. Antes de repetir uma escrita, consulte o recurso correspondente. Para Chat, reconcilie a conversa e suas mensagens; para Listas, repita o mesmo payload e deduplique o evento no seu sistema.