Por que recebo o erro 429 Rate limit exceeded?

Este artigo explica por que POST /v2/emails retorna 429 e como controlar o ritmo dos seus envios para que isso não aconteça. Os mesmos limites se aplicam ao SMTP, em que aparecem como respostas 452.

Sintomas

A API responde com 429 e um destes corpos:

{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Maximum 2 messages per second allowed.",
  "limit": 2,
  "current": 2,
  "retry_after": 1
}

{
  "error": "Daily limit exceeded",
  "message": "Daily sending limit of 5000 messages has been reached.",
  "limit": 5000,
  "current": 5000,
  "retry_after": 41200
}

No SMTP, o comando MAIL FROM falha com 452 4.4.5 Messages per second limit exceeded ou 452 4.5.3 Daily message limit exceeded.

Causa

Cada workspace tem dois limites de envio, compartilhados por todas as chaves de API e pelo SMTP:

• Por segundo. Workspaces novos começam com 2 e-mails por segundo.
• Por dia. Workspaces novos começam com 5.000 e-mails por dia. O contador é zerado à meia-noite UTC.

A API conta cada destinatário como um e-mail, então uma requisição com três endereços em to, cc e bcc usa três. Picos de workers em paralelo, loops de novas tentativas sem backoff e jobs em lote que começam ao mesmo tempo são as causas mais comuns.

Toda resposta de envio inclui cabeçalhos que mostram a sua situação:

Solução

1. Espere e tente de novo. Respeite o retry-after (ou o retry_after no corpo) antes de enviar de novo. Uma requisição com 429 não é enviada nem cobrada, então tentar de novo é seguro. Adicione uma Idempotency-Key para se proteger de novas tentativas no nível da rede.

2. Controle o ritmo do envio. Use uma fila com um limite de concorrência igual ao ratelimit-limit e aplique backoff exponencial depois de um 429, em vez de tentar de novo em um loop apertado.

3. Distribua os envios grandes. Se você atingir o limite diário, agende o restante com scheduled_at para depois da meia-noite UTC ou use uma campanha para e-mails de marketing.

4. Confira os seus limites atuais. O card Sending Limits em Dashboard mostra os seus limites por segundo e por dia e o uso de hoje.

5. Solicite limites maiores. Selecione Request Increase no card Sending Limits e informe os limites de que você precisa, de onde vêm os seus destinatários e por quê. A equipe costuma responder em até 24 horas. No Pro e no Business, os limites também sobem automaticamente enquanto a sua saúde de envio continua boa.

Consulte Limites de requisições para a referência completa e Limites para todas as cotas dos planos.

Ainda com problemas?

Fale com o suporte ou pergunte no Discord. Informe o volume esperado por dia e por segundo e um exemplo de resposta 429.