Skip to main content
A YCloud limita as requisições de API dentro de uma janela de tempo. Os limites se aplicam a uma conta, a um remetente ou a um grupo de endpoints. As requisições que excederem um limite retornam HTTP 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

A conta esgotou sua cota compartilhada de 10.000 requisições por hora . Aguarde pelo menos 1.800 segundos antes de enviar outra requisição sujeita a essa cota. Alternar para um endpoint de gerenciamento diferente não fornece uma nova cota.

Tratar uma resposta 429

  1. Pause requisições que compartilhem a cota esgotada da conta ou do remetente.
  2. Respeite Retry-After quando presente. Não tente novamente antes que esse intervalo expire.
  3. Reduza a simultaneidade e adicione recuo exponencial com jitter.
  4. Limite as repetições por um número de tentativas ou pelo tempo limite da sua aplicação.
  5. Registre em log o endpoint, o método HTTP, o erro code, requestId e o horário da requisição. Exclua chaves de API e dados pessoais.
Se uma resposta bem-sucedida incluir 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 trata Retry-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.
Aplique este exemplo apenas quando a operação for segura para repetição. Para esperas longas, use uma fila agendada para que um worker não precise permanecer ativo.

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. Um POST 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.