Rate Limits

A API do FlowMail aplica limites de requisição por segundo para garantir estabilidade e desempenho para todos os usuários. Os limites variam de acordo com o plano contratado.

Limites por Plano

Cada plano possui um limite de requisições por segundo (req/s). Esse limite se aplica a todas as chamadas de API combinadas.

Plano	Limite (req/s)	Cota Mensal	Burst Máximo
Free	2 req/s	500 verificações	5 requisições
Starter	10 req/s	10.000 verificações	20 requisições
Pro	30 req/s	100.000 verificações	60 requisições
Enterprise	100 req/s	Personalizada	200 requisições

Headers de Resposta

Todas as respostas da API incluem headers que informam o status atual dos seus limites. Use esses headers para monitorar o consumo e evitar bloqueios.

Header	Tipo	Descrição
`X-RateLimit-Limit`	integer	Número máximo de requisições por segundo permitidas no seu plano
`X-RateLimit-Remaining`	integer	Número de requisições restantes na janela atual
`X-RateLimit-Reset`	timestamp	Timestamp Unix (em segundos) de quando a janela atual reseta

EXEMPLO DE HEADERS

HTTP/1.1 200 OK
Content-Type: application/json
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 27
X-RateLimit-Reset: 1709398800

Resposta 429 Too Many Requests

Quando o limite de requisições é excedido, a API retorna o status 429 Too Many Requests com o header Retry-After indicando quantos segundos aguardar.

RESPOSTA 429

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 1
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1709398800

{
  "error": "rate_limit_exceeded",
  "message": "Limite de requisições excedido. Tente novamente em 1 segundo.",
  "retry_after": 1
}

Boas Práticas

Implemente backoff exponencial

Ao receber um 429, aguarde o tempo indicado no header Retry-After. Se continuar recebendo erros, dobre o tempo de espera a cada tentativa.

Use cache de resultados

Os resultados de verificação de e-mail raramente mudam em curto prazo. Armazene os resultados em cache por pelo menos 24 horas para evitar verificações duplicadas e economizar sua cota.

Prefira verificação em lote

Para grandes volumes, use o endpoint de verificação em lote (POST /api/v1/verify/batch) ao invés de múltiplas chamadas individuais. Uma única chamada em lote com 100 e-mails conta como 1 requisição para o rate limit.

Monitore os headers

Verifique os headers X-RateLimit-Remaining em cada resposta e reduza a velocidade das chamadas quando o valor estiver baixo.

PHP - BACKOFF EXPONENCIAL

function verifyWithRetry(string $email, int $maxRetries = 3): array
{
    $attempt = 0;

    while ($attempt < $maxRetries) {
        $response = Http::withToken($apiKey)
            ->get("https://mail.flowsales.online/api/v1/verify/{$email}");

        if ($response->status() !== 429) {
            return $response->json();
        }

        $retryAfter = (int) $response->header('Retry-After', 1);
        $waitTime = $retryAfter * pow(2, $attempt);

        sleep($waitTime);
        $attempt++;
    }

    throw new RateLimitException('Limite de tentativas excedido.');
}