# Troubleshooting de integração

## Como validar antes de ir para produção

Antes de liberar qualquer fluxo:

- teste uma conversa completa
- teste o mesmo contato duas vezes
- confirme que o contexto foi preservado
- confirme que o texto enviado ao cliente sai de `reply`
- registre logs com status HTTP e `thread_id`

## Como usar esta página

Use esta página quando a integração:

- quase funciona
- responde de vez em quando
- perde memória
- devolve o campo errado
- ou simplesmente não entrega nada ao cliente

O jeito mais rápido de depurar é validar em 4 pontos:

1. o que entrou
2. o que foi enviado ao ChatAgent
3. o que o ChatAgent respondeu
4. o que foi devolvido ao provedor

## Primeiro filtro: qual chave você usou

Antes de qualquer outra coisa, confirme:

- você usou a API key do número
- ou você usou a API key geral do tenant

Se usou a chave geral do tenant, confirme também:

- `number_id` está no body

Esse é um dos erros mais comuns hoje.

## Checklist rápido antes de culpar a IA

- body enviado ao ChatAgent
- status HTTP retornado
- `thread_id` recebido
- `reply` recebido
- request de envio ao provedor
- resposta do provedor no envio final

## Erros HTTP mais comuns

### `401 Unauthorized`

Quase sempre significa:

- chave errada
- chave ausente
- header `Authorization` mal formatado

Confirme:

- `Authorization: Bearer SUA_API_KEY`

## `400 Bad Request`

Quase sempre significa uma destas coisas:

- faltou `from`
- faltou `message`
- faltou `number_id` quando a chave usada foi a do tenant

Se o erro apareceu logo no início, olhe primeiro para o body que saiu do seu adaptador.

## `402 Créditos insuficientes`

Significa:

- a conta está sem saldo para processar

## `429 Rate limit excedido`

Quase sempre significa:

- webhook duplicado
- muitos retries
- explosão de eventos em pouco tempo

## `503 Navegador ainda não está pronto`

Significa:

- o serviço ainda está subindo
- ou o provider (ChatGPT via `openai-oauth`, ou DeepSeek — que ainda usa browser interno) não está pronto

Se precisar, valide `/health`.

## Erros funcionais mais comuns

### O cliente recebe resposta, mas a conversa não tem memória

Quase sempre o problema está em `from`.

Se `from` muda entre mensagens, o ChatAgent entende que são conversas diferentes.

### O cliente não recebe nada

As causas mais comuns são:

- o fluxo final não usou `reply`
- o envio ao provedor falhou
- o integrador leu o campo errado da resposta

### O ChatAgent respondeu, mas com o perfil errado

As causas mais comuns são:

- a integração usou a chave do número errado
- ou a integração usou a chave geral do tenant com `number_id` errado

### A API responde 200, mas o texto parece estar indo para conversas misturadas

Quase sempre significa:

- o mesmo `from` foi montado de forma errada
- ou o integrador está trocando o número ou perfil usado na chamada

## Sequência de depuração recomendada

### Passo 1

Logue o body final enviado para o ChatAgent.

### Passo 2

Confirme:

- qual chave foi usada
- se houve `number_id`

### Passo 3

Logue:

- status HTTP
- `thread_id`
- `reply`

### Passo 4

Teste o envio final ao provedor isoladamente.

## Sinais de que está tudo certo

- o mesmo contato gera o mesmo `from`
- a resposta sempre sai de `reply`
- o `thread_id` segue o formato `number:<id>:whatsapp:<from>`
- o perfil usado bate com o número esperado

## Checklist final de depuração

- [ ] eu sei qual chave foi usada
- [ ] se a chave foi a do tenant, `number_id` estava no body
- [ ] eu loguei o body enviado
- [ ] eu loguei `thread_id`
- [ ] eu validei `reply`
- [ ] eu testei o envio final ao provedor separadamente