Erros e idempotência

Status HTTP, resultados ambíguos e repetição segura de requisições.

Leia o status HTTP e o campo error juntos. Uma falha de transporte não significa necessariamente que uma mensagem deixou de ser enviada.

Decida pelo resultado

HTTP / erro	Como tratar
`400`	Corrigir JSON, parâmetros, opções ou allowlist antes de repetir
`401 unauthorized`	Conferir o tipo de header e o token do servidor ou da instância
`403` em grupos	Conferir participação e permissões da conta
`404`	Recurso inexistente; não presumir desconexão
`405`	Corrigir o método; consultar o header `Allow`
`409 whatsapp_disconnected`	Aguardar o fluxo autorizado de reconexão
`409 session_owned_elsewhere`	Sessão pertence a outro worker; não duplicar a instância
`409 media_reupload_pending`	Aguardar o reenvio da mídia e tentar o download depois
`409 idempotency_in_progress`	Aguardar e repetir a mesma requisição com a mesma chave
`422 idempotency_mismatch`	A chave foi reutilizada com método, caminho ou corpo diferentes
`422 send_failed` / `number_not_on_whatsapp`	Falha definitiva desse envio; inspecionar o erro
`429`	Respeitar `Retry-After`
`500 whatsapp_reachout_timelock`	Bloqueio 463 do WhatsApp; observar `error_key` e `details.reachout_timelock.until`
`501 calls_not_supported`	Verificar módulo habilitado e uso de instância `calls`; uma instância de mensagens mantém esse erro
`502 storage_unavailable`	Aguardar recuperação do banco; respeitar `Retry-After`
`503` em readiness	Banco não pronto
`504 send_ambiguous` / `action_ambiguous`	Reconciliar pelo ID e pelos eventos antes de reenviar

Resultado ambíguo

Um 504 pode ocorrer depois de o WhatsApp aceitar a operação. Guarde o identificador devolvido e consulte o status ou os eventos. Repetir com uma chave nova pode duplicar o efeito.

Os aliases messageid, messageId e id dos envios se referem ao ID da mensagem do WhatsApp. Na edição, editId identifica a ação de edição e o ID original permanece separado.

Rotas com idempotência

Operações	Retenção
`POST /instance/init`	15 minutos
`/send/*`, ações em mensagens e mutações de grupo indicadas no contrato	24 horas

A página de cada endpoint informa se ele oferece Idempotency-Key. Não há garantia geral para qualquer POST.

http

Idempotency-Key: operacao-exemplo-001

Crie uma chave por operação de negócio. Em uma repetição, mantenha a mesma chave, o método, o caminho e os mesmos bytes do corpo. Alterar espaços ou a ordem das chaves no JSON altera o hash.

Replay de requisição

Idempotency-Replayed: true indica uma resposta guardada. Respostas transitórias 409, 429 e 5xx, exceto 504, liberam a chave. Resultados concluídos e ambíguos 504 permanecem guardados durante a retenção.

Repetir um 504 e receber a mesma resposta não autoriza criar outra chave para o mesmo envio.

Limites e correlação

Use X-Request-Id para correlacionar falhas sem registrar tokens ou conversas. O corpo geral aceita 64 KiB; /send/media aceita 48 MiB de JSON e /group/updateImage 12 MiB. Bytes UTF-8 e caracteres não são a mesma medida.

O orçamento do handler de envio é de 44 segundos. Configure o timeout do cliente de forma compatível e implemente a reconciliação de resultados ambíguos.

Reentrega de eventos

Idempotência de requisição e deduplicação de webhook são responsabilidades distintas. Para eventos, deduplique por servidor, instância e X-AtendroZAP-Event-Id. POST /v1/events/{id}/replay pode repetir um efeito já processado.