Rate limits y cuotas

MailerDash aplica dos tipos de límites a los envíos: un límite de tasa por minuto (rate_per_min) y una cuota mensual (monthly_quota). Ambos se definen a nivel de plan (package) y pueden tener overrides por cuenta configurados por el equipo de MailerDash.

---

Límite de tasa (rate_per_min)

Controla cuántos requests de envío puede hacer tu API key en una ventana de 60 segundos. Si superas este límite, la API responde con HTTP 429.

El valor por defecto para cuentas sin plan asignado es de 30 requests/minuto. Tu plan puede otorgarte un límite mayor.

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Please slow down."
  }
}

La respuesta incluye los headers estándar de rate limit:

Header	Descripción
RateLimit-Limit	Límite máximo de requests en la ventana
RateLimit-Remaining	Requests restantes en la ventana actual
RateLimit-Reset	Timestamp Unix cuando se resetea la ventana

Consejo

Implementa un mecanismo de retry con backoff exponencial en tu integración para absorber picos de tráfico sin perder envíos. Al recibir un 429, espera al menos el tiempo indicado por RateLimit-Reset antes de reintentar.

---

Cuota mensual (monthly_quota)

Es el número máximo de correos que puedes enviar en un periodo de facturación (mes). El contador se resetea al inicio de cada nuevo periodo.

Cuando alcanzas la cuota mensual, los envíos adicionales son rechazados con HTTP 429:

{
  "error": {
    "type": "rate_limit_error",
    "code": "monthly_quota_exceeded",
    "message": "Monthly quota exceeded: 5000/5000 emails sent this month"
  }
}

Overage

Si tu plan lo contempla, puedes seguir enviando después de agotar tu cuota base pagando por correo adicional (overage). Si el plan no ofrece overage, los envíos que excedan la cuota serán bloqueados con el código overage_not_offered.

---

Consultar tu uso actual

GET /v1/client/usage
Authorization: Bearer $MAILERDASH_API_KEY

Este endpoint retorna el uso del periodo actual por cada API key vinculada a tu cuenta, junto con los límites del plan activo:

{
  "subscriptions": [
    {
      "package_id": "pro",
      "package_name": "Pro",
      "monthly_quota": 50000,
      "rate_per_min": 120,
      "billing_period": "monthly",
      "started_at": "2026-06-01T00:00:00.000Z"
    }
  ],
  "keys": [
    {
      "id": "mi-key",
      "label": "Producción",
      "sent_this_period": 12340,
      "monthly_quota": 50000,
      "quota_remaining": 37660
    }
  ],
  "next_reset": "2026-07-01T00:00:00.000Z"
}

El campo next_reset indica cuándo se reiniciará el contador mensual.

---

Límites de payload

Además de los límites de tasa y cuota, existen límites en el tamaño de las requests:

• Attachments: si el total de adjuntos supera el límite permitido, recibirás un 413 con código payload_too_large. El campo param indicará attachments.

---

Resumen de códigos de error relacionados

code	HTTP	Descripción
rate_limit_exceeded	429	Superaste el límite de requests por minuto
monthly_quota_exceeded	429	Superaste la cuota mensual de tu plan
overage_not_offered	400	El plan no permite envíos extra tras agotar la cuota
payload_too_large	413	El body del request excede el tamaño máximo

Ver la referencia completa en /reference/platform/ y el manejo de errores en /referencia/errores/.