Erros
Os erros usam códigos de status convencionais com umdetail legível por máquina:
Erros estruturados sempre carregam um
code estável sobre o qual você pode ramificar; as chaves adicionais (como conflicting_contact_id em um contato duplicado) fornecem o necessário para resolver. Cada formato de erro está publicado na referência da API.
Enviar um modelo
POST /v1/templates/{id}/send recusa a solicitação inteira em vez de enfileirar parte dela, então uma recusa nunca deixa você com o envio pela metade nem custa nada. Os códigos que vale ramificar:
GET /v1/templates/{id}/send-requirements diz o que um modelo precisa antes de enviar, então a maioria destes nunca precisa acontecer.
Limites de uso
Cada organização tem um orçamento compartilhado de 20 solicitações por segundo entre todas as suas chaves — 5 por segundo durante o teste gratuito. Acima do orçamento, as solicitações retornam429 com um cabeçalho Retry-After (segundos; sempre 1, porque a janela é de um segundo).
Cada resposta — inclusive o 429 — carrega o seu orçamento atual, para você dosar sem contar chamadas por conta própria:
Leia
X-RateLimit-Remaining e reduza o ritmo conforme ele se aproxima de zero, em vez de correr até o 429. Se a sua integração realmente precisar de mais, fale com a gente.
Uma solicitação é uma solicitação, não importa quanto ela faça.
POST /v1/templates/{id}/send conta uma vez só, leve um destinatário ou cem — então agrupar destinatários em um único envio é a forma mais barata de ficar dentro do orçamento. O que limita o volume real de mensagens é o próprio limite móvel de 24 horas do WhatsApp, não este.Repetir com segurança
POST /v1/templates/{id}/send aceita um cabeçalho Idempotency-Key. Envie a mesma chave de novo dentro de 24 horas e você recebe a campanha original em vez de um segundo envio — que é o que você quer depois de um timeout, quando realmente não dá para saber se a solicitação chegou. Use uma chave nova para cada envio distinto.
Paginação
Os endpoints de listagem retornam:next_cursor de volta como ?cursor= para buscar a próxima página; um cursor null significa que você chegou ao fim. Os cursores são opacos — não os interprete.
As listas de propriedades e etapas do funil não são paginadas: retornam o conjunto completo, sem next_cursor.
Compatibilidade
Esta é uma API jovem e em rápida evolução — espere que ela mude. Dois hábitos mantêm sua integração estável:- A maioria das mudanças é aditiva: novos endpoints, novos parâmetros opcionais, novos campos de resposta, novos valores em campos de texto. Tolere campos e valores desconhecidos — ignore o que não reconhecer.
- Cada mudança do contrato aparece no changelog — confira quando algo parecer diferente.