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).

Mailbeam es solo de pago. Las peticiones en vivo de una cuenta sin un plan de pago activo devuelven un 402 con error: "plan_required"; la cuenta, sus claves y su historial se conservan. Las claves de test funcionan en todas las cuentas, devuelven resultados simulados y nunca cuentan para la cuota.

Cuotas mensuales

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

PlanVerificaciones/mes
Mini1000
Starter5000
Growth25 000
Pro100 000
Scale500 000
EnterpriseA medida

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

PlanPeticiones/segundo
Mini5
Starter10
Growth25
Pro50
Scale200
EnterpriseA medida

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
CabeceraDescripción
X-RateLimit-LimitMáximo de peticiones por segundo de tu plan
X-RateLimit-RemainingPeticiones que quedan en el segundo actual
X-RateLimit-ResetMarca de tiempo Unix en que se reinicia la ventana por segundo
X-Quota-LimitCuota mensual de verificaciones
X-Quota-RemainingVerificaciones que quedan este mes
X-Quota-ResetMarca de tiempo Unix en que se reinicia la cuota mensual

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, todos los planes de pago siguen respondiendo y facturan las verificaciones de más como exceso: no te bloqueamos. Un plan sin facturación por exceso respondería en su lugar un 429 con error: "quota_exceeded". Sin un plan de pago activo, las peticiones en vivo devuelven un 402 con error: "plan_required" hasta que elijas un plan.

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