429 Too Many Requests com a resposta de erro padrão.
Limites da Messaging API
rps significa requisições por segundo. Um remetente é um número de telefone comercial do WhatsApp.
A maioria dos endpoints tem um limite de 200 rps por conta. Os endpoints de envio do WhatsApp usam os limites por remetente mostrados acima. Consulte a documentação de taxa de transferência da Meta para obter mais informações sobre upgrades automáticos.
Envios do WhatsApp enfileirados e diretos
A YCloud contabiliza os dois endpoints de envio do WhatsApp separadamente. O endpoint enfileirado/v2/whatsapp/messages aceita até 200 rps por remetente, enquanto a YCloud envia mensagens enfileiradas para a Meta a 60 rps. A aceitação na fila não significa que a Meta tenha aceitado ou entregue a mensagem.
Evite enviar a uma taxa alta por ambos os endpoints com o mesmo remetente ao mesmo tempo. Os envios enfileirados e diretos ainda usam o mesmo número de telefone comercial do WhatsApp, portanto, o tráfego combinado de ambos pode atingir o limite da Meta e causar falhas.
Limites da Management API
A maioria das APIs sem uma política documentada separada são APIs de gerenciamento. Esses endpoints compartilham uma cota por conta: 200 requisições por segundo e 10.000 requisições por hora. Ambos os limites se aplicam; você não pode sustentar 200 rps durante uma hora inteira. As requisições para um endpoint de gerenciamento consomem a cota disponível para os demais. A política compartilhada inclui:/v2/balance/v2/webhookEndpoints/*/v2/whatsapp/businessAccounts/*/v2/whatsapp/phoneNumbers/*/v2/whatsapp/templates/*/v2/whatsapp/messages/{id}- Outras APIs sem uma política documentada separadamente
Ler cabeçalhos de limite de taxa
A YCloud inclui informações sobre limite de taxa na maioria das respostas da API. Leia os cabeçalhos quando estiverem presentes em vez de presumir que todos os endpoints têm a mesma cota.Os cabeçalhos
RateLimit-* estão em versão beta e podem sofrer alterações. O formato de cabeçalho documentado da YCloud
segue a especificação de limite de taxa IETF draft-06. Trate os parâmetros de política
como informativos e mantenha seu cliente tolerante a parâmetros
adicionais.Exemplo: cota horária compartilhada esgotada
Tratar uma resposta 429
- Pause requisições que compartilhem a cota esgotada da conta ou do remetente.
- Respeite
Retry-Afterquando presente. Não tente novamente antes que esse intervalo expire. - Reduza a simultaneidade e adicione recuo exponencial com jitter.
- Limite as repetições por um número de tentativas ou pelo tempo limite da sua aplicação.
- Registre em log o endpoint, o método HTTP, o erro
code,requestIde o horário da requisição. Exclua chaves de API e dados pessoais.
Retry-After, atrase as requisições subsequentes; não reenvie a requisição que já obteve sucesso. Monitore RateLimit-Remaining e RateLimit-Reset para diminuir o ritmo antes que a cota se esgote.
Repetir com recuo e jitter
Este exemplo em JavaScript trataRetry-After como uma espera mínima. O limite de recuo restringe o atraso de jitter da aplicação; ele não reduz uma espera solicitada pelo servidor. As configurações de tentativas e atrasos são escolhas da aplicação, não limites da API.
Controlar a simultaneidade e as repetições
Use uma fila delimitada e um limite compartilhado de workers. Evite loops de repetição independentes onde cada um presume que a cota total da conta ou do remetente está disponível. Restaure o tráfego gradualmente após o término da limitação. UmPOST repetido pode criar outro recurso ou enviar outra mensagem. Verifique primeiro as orientações de nova tentativa do endpoint e o resultado que você salvou. Onde houver suporte, mantenha um externalId estável, mas não o trate como uma chave de idempotência universal. Armazene o ID de resposta da YCloud e reconcilie resultados ambíguos antes de reenviar.
Monitore o volume de requisições, respostas 429, latência, contagem de novas tentativas e tempo na fila por endpoint e remetente. Consulte Práticas recomendadas da API de mensagens do WhatsApp para enfileiramento, reconciliação e prevenção de duplicatas.
