Formato e catálogo de erros

Formato e catálogo de erros

Envelope {error, code}, catálogo completo de status codes / error codes da API WaBlast.

Envelope de erro

Toda resposta de erro (4xx/5xx) usa o mesmo envelope:

{
  "error": "Mensagem legível (pt-BR)",
  "code": "MACHINE_READABLE_CODE"
}
  • error — texto humano, pt-BR, pode mudar.
  • code — discriminador estável; use sempre o code na sua lógica, nunca o texto.

Sucesso retorna o JSON do recurso cru (sem envelope { success, data }).

Sempre que for reagir programaticamente a um erro, compare contra o code (string estável), não contra o texto em error.

Catálogo de status codes / error codes

HTTP code Quando
400 INVALID_BODY Validação Zod falhou (mensagem do primeiro erro incluída)
400 BAD_REQUEST Erro 4xx de framework (multipart inválido, content-type, parse de body)
400 NO_FILE Upload multipart sem o campo file
400 TEMPLATE_PENDING Tentativa de editar template com status PENDING
400 INVALID_URL URL de webhook inválida / não-https
400 FORBIDDEN_URL URL de webhook aponta para IP privado/loopback (proteção SSRF)
401 UNAUTHENTICATED API key ausente, inválida, revogada ou expirada
402 SUBSCRIPTION_REQUIRED Assinatura inativa (e fora de período de graça válido)
403 CONTACT_OPTED_OUT Contato marcado como blocked (opt-out LGPD)
404 ACCOUNT_NOT_FOUND Conexão WhatsApp não existe ou é de outro usuário
404 MESSAGE_NOT_FOUND Mensagem não existe ou é de outro usuário
404 TEMPLATE_NOT_FOUND Template não existe ou é de outro usuário
404 ENDPOINT_NOT_FOUND Webhook endpoint não existe ou é de outro usuário
404 DELIVERY_NOT_FOUND Delivery não existe ou é de outro usuário
404 NOT_FOUND Rota inexistente
409 WINDOW_CLOSED Mensagem free-form (texto/mídia) fora da janela de 24h — use template
409 ACCOUNT_TOKEN_INVALID Token Meta da conexão expirou — reconecte no painel
409 IDEMPOTENCY_IN_FLIGHT POST com a mesma Idempotency-Key ainda processando
409 ENDPOINT_LIMIT Limite de 10 webhook endpoints por usuário atingido
409 REPLAY_NOT_ALLOWED Delivery não está em estado replayável (já em fila/in-flight)
413 — Arquivo de mídia maior que o limite (64 MB no gateway)
422 META_ERROR Meta rejeitou a operação (mensagem da Meta no error)
429 RATE_LIMITED Cota por minuto da chave excedida (+ Retry-After)
429 META_RATE_LIMIT Meta retornou 429 (+ Retry-After opcional)
429 TIER_DAILY_CAP_REACHED Cap diário do tier Meta atingido
500 INTERNAL_ERROR Exceção não tratada
Pular para o conteúdo