Erros e retry
A API usa três formatos de corpo de erro, dependendo de onde o problema foi detectado. Vale tratar
os três — quem trata só um vai logar undefined no dia em que o outro aparecer.
Os formatos
400 — validação do payload
O mais comum. Vem com a lista de todos os campos problemáticos de uma vez:
HTTP/1.1 400 Bad Request
{
"erro": "Validação falhou",
"detalhes": [
{ "campo": "ChaveExterna", "mensagem": "'Chave Externa' must not be empty." },
{ "campo": "Mensagens[2].UrlAudio", "mensagem": "URL do áudio precisa ser https." }
]
}
campo usa a notação do servidor (PascalCase, índice de array entre colchetes), então
Mensagens[2].UrlAudio é a terceira mensagem do array — contando do zero.
400 — regra de negócio
Detectado mais adiante, uma mensagem só:
HTTP/1.1 400 Bad Request
{ "erro": "Interlocutor inválido: 'Atendente'. Válidos: Operador, Cliente, Bot, Sistema" }
401 — autenticação
Formato próprio, com messages no plural:
HTTP/1.1 401 Unauthorized
{ "messages": ["Chave de ingestão inválida."] }
500 — erro interno
HTTP/1.1 500 Internal Server Error
{ "erro": "Erro interno" }
Em produção não vem detalhe — de propósito. Se você precisa investigar, envie a chaveExterna e o
horário aproximado para o time do QA Analytics.
mensagem = corpo.detalhes?.map(d => `${d.campo}: ${d.mensagem}`).join(' · ')
?? corpo.erro
?? corpo.messages?.join(' · ')
?? `HTTP ${status}`
Mensagens de validação que você vai encontrar
Estrutura
| Mensagem | Causa |
|---|---|
'Chave Externa' must not be empty. | chaveExterna ausente ou em branco. |
Interação de texto exige ao menos uma mensagem. | /whatsapp com mensagens vazio. |
Mensagem sem texto e sem áudio. | Uma mensagem sem texto e sem urlAudio. |
Interlocutor inválido: '...'. Válidos: Operador, Cliente, Bot, Sistema | Valor fora da lista fechada. |
Áudio
| Mensagem | Causa |
|---|---|
URL do áudio vazia. | Campo presente, em branco. |
URL do áudio inválida: '...'. | Não é URL absoluta. |
URL do áudio precisa ser https. | Esquema http. |
URL do áudio aponta para um host local: '...'. | localhost, metadata etc. |
URL do áudio precisa apontar para um nome, não para um IP. | Host numérico. |
URL do áudio precisa terminar com a extensão do arquivo. | Caminho sem extensão. |
Extensão de áudio não permitida: '...'. Aceitas: ... | Formato fora da lista. |
Conversa com mais de 50 áudios não é aceita numa ingestão só. | Teto por conversa. |
Detalhe em URLs de áudio.
Política de retry
| Código | Fazer | Por quê |
|---|---|---|
201, 200 | Sucesso. Registrar interacaoId e resultado. | — |
400 | Não retentar igual. Corrigir o payload. | O mesmo payload dá o mesmo erro para sempre. Retentar só gera log. |
401 | Não retentar. Alertar operação. | Chave errada ou conta suspensa; nenhum dos dois melhora com tentativa. Ver Autenticação. |
5xx, timeout, erro de rede | Retentar com backoff exponencial. | É seguro: a idempotência garante que não haverá duplicata. Ver Idempotência. |
Backoff sugerido
5s → 30s → 2min → 10min → 1h → 6h → desiste e alerta
Sete tentativas ao longo de umas oito horas. É generoso de propósito: como o reenvio não cria duplicata, o custo de tentar de novo é uma requisição — e o custo de desistir cedo é uma conversa perdida, que não se refaz.
Depois da última tentativa, guarde o payload em algum lugar do qual dê para reenviar manualmente. Ele é a única cópia daquele atendimento que a auditoria vai ver, e um log com a mensagem de erro não permite reprocessar.
O que não é erro
Três respostas que parecem problema e não são:
| Resposta | Significa |
|---|---|
200 com resultado: "Duplicada" | Reenvio reconhecido. A interação está no sistema. Não é erro. |
201 com aguardandoLimite: true | Gravada, esperando saldo do cliente. Nada a fazer. Ver Limite de uso. |
201 com pendenteMetadadoObrigatorio: true | Falta um metadado que o cliente marcou como obrigatório. A auditoria acontece normalmente. Ver Metadados. |
Erro que só aparece depois
A ingestão pode responder 201 e a interação ir para Falha no processamento. Isso não volta para
você — o motivo fica escrito na tela do cliente.
Os casos conhecidos:
| Causa | Como evitar |
|---|---|
Ligação enviada sem mensagens | Enviar a ligação já transcrita. Ver Enviar uma ligação. |
| Áudio inacessível no download — URL expirada, arquivo removido, host fora | URL durável. Ver URLs de áudio. |
| Arquivo maior que 25 MB | Idem. |
Se o cliente relatar interações em Falha em volume, é sinal de um destes três — e os três se resolvem
do seu lado.