Códigos de erro

Toda resposta de erro vem com um campo errorCode (string) que identifica a causa, além do status HTTP. Use o errorCode para tomar decisões no seu código — ele é estável; mensagens podem mudar.

Formato padrão de erro

json

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "O campo 'email' nao tem formato valido.",
    "details": {
      "field": "email",
      "value": "joao@@empresa"
    }
  }
}

Autenticação e permissão

Código	Status HTTP	O que significa	O que fazer
`UNAUTHORIZED`	401	Token ausente, inválido ou expirado.	Renovar o JWT em GET /v1/auth/token. Verificar o header Authorization: Bearer ...
`FORBIDDEN`	403	O usuário está autenticado mas não tem permissão para essa ação.	Verificar role/escopo do usuário; pedir ao admin da organização para promover.
`MODULE_NOT_ENABLED`	403	O módulo solicitado não está habilitado no plano atual da organização.	Fazer upgrade de plano em /v1/billing/checkout ou habilitar a feature flag correspondente.
`INTEGRATION_EXPIRED`	401	O token OAuth da conexão externa expirou.	Chamar POST /v1/connections/{id}/refresh ou reautorizar o provedor.
`INTEGRATION_REVOKED`	401	O usuário revogou o acesso da Adalink no provedor (Google, Slack...).	Reautorizar a conexão via /v1/connections/oauth/authorize.

Validação de dados

Código	Status HTTP	O que significa	O que fazer
`VALIDATION_FAILED`	400	Um ou mais campos do request não passaram na validação.	Inspecionar `error.details` para a lista de campos inválidos. Corrigir e reenviar.
`INVALID_EMAIL`	400	O email informado não tem formato válido.	Garantir formato RFC 5322 (ex: nome@dominio.com).
`INVALID_UUID`	400	Um identificador enviado não é UUID v7 válido.	Usar UUID v7 (verifique se o ID veio realmente de uma resposta da API).
`TYPE_MISMATCH`	400	Tipo de dado incompatível com o esperado pelo endpoint.	Confira o schema do endpoint no Swagger interno (/api/docs) ou na referência.
`MISSING_REQUIRED_FIELD`	400	Um campo obrigatório não foi enviado.	Verificar `error.details.field` e incluir no body.

Recursos não encontrados

Código	Status HTTP	O que significa	O que fazer
`CONVERSATION_NOT_FOUND`	404	A conversa solicitada não existe ou pertence a outra organização.	Verifique se o conversationId está correto e pertence à mesma organização do token.
`ENTITY_NOT_FOUND`	404	O recurso solicitado não existe.	Conferir o ID e a organização. Pode ter sido deletado.
`DUPLICATE`	409	Tentativa de criar um recurso que já existe (chave única violada).	Reutilizar o recurso existente ou enviar valor único diferente.

Limites e cota

Código	Status HTTP	O que significa	O que fazer
`RATE_LIMITED`	429	Você ultrapassou o limite de requisições por minuto do seu plano.	Aguardar o tempo indicado pelo header Retry-After antes de retentar. Considerar upgrade.
`INSUFFICIENT_CREDITS`	402	Saldo de créditos (adacoins) insuficiente para executar essa ação.	Adicionar créditos via /v1/billing/checkout ou esperar a renovação do ciclo.
`INTEGRATION_RATE_LIMIT`	429	A integração externa (provider) atingiu o limite dele, não o nosso.	Aguardar e retentar; alguns providers exigem backoff exponencial mínimo de 60s.

Erros do servidor

Código	Status HTTP	O que significa	O que fazer
`INDEXING_FAILED`	500	Falha ao indexar o documento na base de conhecimento.	Tentar novamente. Se persistir, verificar formato e tamanho do arquivo.
`PARSE_FAILED`	422	Não conseguimos extrair conteúdo do arquivo enviado.	Confira se o arquivo não está corrompido nem protegido por senha.
`PROCESSING_FAILED`	500	Erro inesperado no pipeline de processamento.	Retentar a operação. Se persistir, abrir ticket de suporte com o X-Request-Id da resposta.
`XLSX_TIMEOUT`	504	Parse de planilha XLSX excedeu o tempo limite.	Reduzir o tamanho da planilha ou separar em arquivos menores.
`XLSX_CORRUPTED`	422	Arquivo XLSX corrompido ou em formato não suportado.	Reabrir e salvar a planilha em formato válido (.xlsx).
`FETCH_FAILED`	502	Falha ao baixar o arquivo da URL informada.	Verificar se a URL ainda é válida e está acessível publicamente.
`INTEGRATION_PROVIDER_ERROR`	502	A integração externa retornou um erro inesperado.	Retentar; se persistir, verificar status do provider (Google Status, Slack Status...).
`MCP_CLIENT_UNAVAILABLE`	503	O servidor MCP (Model Context Protocol) está indisponível.	Aguardar alguns segundos e retentar. Verificar configuração do MCP server.