Limites de taxa

Os limites de requisição, criação e envio que uma implantação MepMail aplica — e como trabalhar dentro deles.

O MepMail aplica limites em quatro camadas: taxa de requisições HTTP, proteção de credencial, criação de recursos e volume de envio.

Taxa de requisições HTTP

Duas janelas fixas de um minuto valem para toda chamada feita com chave de API, e um 429 rate_limit_exceeded responde pela que estiver cheia:

Janela	Padrão	Definida por
Por chave de API	600 requisições/minuto	`API_RATE_LIMIT_PER_MINUTE`
Por time, somando todas as chaves	3.000 requisições/minuto	Implantação

Criar mais chaves não multiplica o teto — a janela do time cobre todas elas.
A janela fixa zera no minuto, então uma rajada que enche uma janela e outra que enche a seguinte podem passar o dobro da cota em poucos segundos. Dê ritmo ao cliente em vez de encher a janela.
Um 429 traz Retry-After (segundos inteiros restantes na janela): espere esse tempo, ou faça backoff exponencial, antes de tentar de novo.
As respostas não trazem cabeçalhos RateLimit-*: hoje o 429 e o Retry-After são como o cliente descobre que passou do limite.
Chamadas pelo servidor MCP hospedado são contadas por usuário autenticado — 600 chamadas/minuto, a mesma configuração — porque uma concessão OAuth não tem chave de API para contar.

Espere. Respeite o Retry-After quando ele vier; sem ele, faça backoff exponencial com jitter: 1s, 2s, 4s, 8s… Um cliente que repete na hora só reenche a janela e continua recusado.
Não repita outros 4xx. Só 429 e 409 concurrent_idempotent_requests valem uma nova tentativa; o resto da faixa 4xx é determinístico (Erros).
Torne a repetição segura. POST /emails e POST /emails/batch aceitam um Idempotency-Key: reuse a mesma chave para que uma repetição depois de um timeout ou de um 429 não entregue duas vezes.
Reduza o tráfego. Envie até 100 e-mails por chamada (POST /emails/batch) e até 1.000 contatos por chamada (POST /contacts/batch), e serialize rajadas em vez de disparar tudo junto.
Suba o teto se a carga for realmente maior: a janela por chave é API_RATE_LIMIT_PER_MINUTE em uma implantação auto-hospedada. Na Nuvem, fale com o suporte — subir a janela do time é decisão do operador.

Mais de 20 tentativas de autenticação falhas por minuto vindas de um mesmo IP respondem 429 ("Too many failed authentication attempts", com Retry-After). Isso existe para tornar a força bruta inútil — pare de repetir credenciais erradas e confira a chave.
Chaves inválidas, revogadas ou usadas fora do nível de permissão respondem 401/403, nunca são aceitas em silêncio (Erros).

10 domínios por hora por time. Criar uma identidade de envio provisiona um recurso compartilhado no AWS SES, então o teto evita que um time esgote a cota da conta. Ele zera a cada hora. O número de domínios do plano é um limite separado e continua valendo.
10 registros de cliente OAuth de MCP por 15 minutos por endereço. Um cliente que precise se registrar de novo deve reusar o registro existente — registrar a cada inicialização é o que estoura esse limite.

Plano	Incluído	Período	Passando do teto
Free	100	dia UTC	Envios ficam parqueados como `queued_quota` e drenam depois da virada do dia; quando o backlog parqueado chega a 3× o teto diário, novos envios são recusados com `429 daily_quota_exceeded`
Starter	1.500	dia UTC	Mesmo comportamento de parqueamento e mesma recusa com 3× de backlog
Pro / Scale	volume comprado	mês	Excedente cobrado por 1.000 quando ligado; caso contrário, `429 monthly_quota_exceeded`

O parqueamento é deliberado: um envio diário acima da cota é aceito e entra na fila — a API responde 200 com um id — para uma rajada perto da meia-noite não se perder. Leia o status do e-mail para distinguir um envio parqueado de um na fila.
Planos mensais com excedente ligado ainda param no rígido de 5× o volume incluído: uma integração descontrolada (ou uma chave roubada) nunca gera uma conta sem fim.
A taxa de envio por segundo é limitada pela cota de SES da implantação — 14/s por padrão, acompanhando a taxa real da conta conforme ela cresce. Os broadcasts são ritmados para deixar folga ao transacional (30% de reserva por padrão).
O envio pode parar antes da cota: um time cuja taxa de bounce duro ou de reclamação cruze o guardrail recebe 403 sending_paused, e o envio de broadcast espera a taxa regional da plataforma (403 broadcasts_paused). Os dois estão em Erros.

50 destinatários por e-mail (to + cc + bcc somados).
100 e-mails por chamada em lote; um array acima do teto responde 422.
Anexos (somados na mensagem, medidos depois da decodificação): 1 MB no Free e Starter, 5 MB no Pro, 10 MB no Scale.

Veja Cobrança para preços e a escada completa.

600 chamadas por minuto por usuário autenticado no endpoint MCP hospedado (API_RATE_LIMIT_PER_MINUTE), depois 429 rate_limit_exceeded. As chamadas não são cobradas na janela de chaves do time.
O pacote local @mepmail/mcp fala com a API REST usando uma chave de API, então ali valem as janelas por chave e por time acima.
O registro dinâmico de cliente OAuth do MCP é limitado por endereço (10 por 15 minutos); um cliente que precise se registrar de novo deve reusar o registro existente.