Límites de tasa

Mailbeam aplica dos tipos de límite: cuotas mensuales (por plan) y límites de tasa por segundo (por clave de API).

Cuotas mensuales

Cada plan incluye un número fijo de verificaciones por mes natural:

Tu cuota se reinicia a medianoche UTC en el aniversario de tu facturación. Puedes consultar tu consumo actual en /v1/account/usage.

Límites de tasa por segundo

Las peticiones al endpoint por lotes cuentan como 1 petición por envío de lote, no por cada email del lote.

Cabeceras de límite de tasa

Toda respuesta incluye cabeceras con el estado actual de tu límite:

X-RateLimit-Limit: 50
X-RateLimit-Remaining: 47
X-RateLimit-Reset: 1716825600
X-Quota-Limit: 50000
X-Quota-Remaining: 43218
X-Quota-Reset: 1719532800

Cómo tratar las respuestas 429

Cuando superas el límite de tasa por segundo, recibes un 429 Too Many Requests:

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Please slow down.",
  "retry_after": 1
}

El campo retry_after indica los segundos que hay que esperar antes de reintentar.

Estrategia de reintentos recomendada

Usa retroceso exponencial con jitter para tratar los límites con solidez:

async function verifyWithRetry(email, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await verifyEmail(email);
    } catch (err) {
      if (err.status === 429 && attempt < maxRetries - 1) {
        const retryAfter = err.retryAfter ?? 1;
        const jitter = Math.random() * 1000; // 0–1000 ms
        const delay = retryAfter * 1000 * Math.pow(2, attempt) + jitter;
        await new Promise((r) => setTimeout(r, delay));
      } else {
        throw err;
      }
    }
  }
}

Para verificar en volumen, usa el endpoint por lotes en lugar de lanzar peticiones sueltas en un bucle. El endpoint por lotes gestiona la concurrencia por su cuenta.

Cuota agotada

Cuando se agota tu cuota mensual, las peticiones devuelven un 429 con error: "quota_exceeded". En los planes de pago se activa automáticamente la facturación por exceso: no te bloqueamos. En el plan Free, las peticiones se rechazan hasta el siguiente reinicio.

Recibes avisos por email cuando llegas al 80 % y al 100 % de tu cuota mensual.