Pular para o conteúdo principal

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.

Um parser que cobre os três
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​

MensagemCausa
'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, SistemaValor fora da lista fechada.

Áudio​

MensagemCausa
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ódigoFazerPor quê
201, 200Sucesso. Registrar interacaoId e resultado.—
400Não retentar igual. Corrigir o payload.O mesmo payload dá o mesmo erro para sempre. Retentar só gera log.
401Não retentar. Alertar operação.Chave errada ou conta suspensa; nenhum dos dois melhora com tentativa. Ver Autenticação.
5xx, timeout, erro de redeRetentar 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.

Fila de mortos (dead letter)

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:

RespostaSignifica
200 com resultado: "Duplicada"Reenvio reconhecido. A interação está no sistema. Não é erro.
201 com aguardandoLimite: trueGravada, esperando saldo do cliente. Nada a fazer. Ver Limite de uso.
201 com pendenteMetadadoObrigatorio: trueFalta 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:

CausaComo evitar
Ligação enviada sem mensagensEnviar a ligação já transcrita. Ver Enviar uma ligação.
Áudio inacessível no download — URL expirada, arquivo removido, host foraURL durável. Ver URLs de áudio.
Arquivo maior que 25 MBIdem.

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.