Erros e limites

Códigos por superfície

Código	Onde	Significa
`200`	todas	Sucesso
`202`	webhook de ingestão	Aceito; o trabalho acontece depois
`400`	`/webhooks/*`	Envelope inválido ou id de contato ausente
`401`	`/api/*`	Sessão ausente (`session_required`) ou inválida (`session_invalid`)
`401`	`/webhooks/*`	Credencial da URL ou IP fora da allowlist
`403`	`POST /session`	Sessão recusada — sempre `account_not_found`
`403`	`/api/*`	Recusado pela API da Allbound IA (recurso não habilitado na conta)
`404`	`/api/*`	Rota fora da allowlist do proxy
`500`	`/webhooks/update-contact`	Falha ao gravar na fila
`502`	`/api/usage`	Dependência indisponível
`502`	`/api/*`	O Insights não conseguiu credencial junto à Allbound IA (`upstream_auth_failed`)

As respostas são genéricas de propósito

Duas recusas não dizem o motivo, e isso não é falta de caprichoso:

403 account_not_found em /session — não distingue tenant inexistente,
conta que não bate e usuário inválido. Distinguir permitiria enumerar cid
válidos.

401 unauthorized nos webhooks — não distingue IP bloqueado, client_id
desconhecido e token errado.

Nos dois casos o motivo real vai para o log estruturado do Insights, no campo
reason. Depuração se faz no log, não na resposta. A tabela de reason de
sessão está em Sessão do embed.

`401` × `403` × `404`

Vale separar porque a ação é diferente em cada caso:

401 — a sessão morreu. Chame /session de novo. Reemitir resolve.
403 — a credencial está certa, o acesso é que não existe. Reemitir não
resolve: ou a conta não tem o recurso habilitado, ou os dados do embed não
batem com o registro do tenant.
404 em /api/* — a rota não está na allowlist do proxy. Nenhuma sessão
faz essa rota existir; ver API disponível.

Limites

Limite	Valor
Sessão do embed	1 hora
Tentativas de `POST /session`	30 por minuto, por IP
Corpo de `POST /session`	16 KB
Corpo dos webhooks	1 MB
Cache de `GET /api/usage`	1 hora por tenant

O 429 não é usado: excesso de tentativas em /session recebe o mesmo 403
genérico das outras recusas.

Os limites das rotas repassadas — tamanho de pergunta, upload de relatório — são
os da API da Allbound IA, não do Insights.

Reprocessamento

A ingestão de conversas é segura em retry: a mesma conversa reenviada não duplica
análise. Ver Webhooks.

POST /session pode ser chamado quantas vezes for preciso — cada chamada emite
um token novo, e os anteriores continuam valendo até expirar.

Quando nada parece errado e mesmo assim não funciona

Três causas respondem pela maioria dos casos:

O menu abre e mostra "conta não encontrada" — a trinca cid/ha/hu não
resolve. Quase sempre o ha não corresponde ao id de conta registrado para
aquele cid.
O Insights abre, mas não há nada para analisar — o webhook de ingestão não foi
assinado, ou aponta para o segredo errado. Confira o log: 401 recorrente em
/webhooks/partner-crm é o sintoma.
Tudo responde 403 nas rotas de Insights — a conta na Allbound IA está sem
o recurso de análise conversacional habilitado.