Limites de débit

Mailbeam applique deux types de limites : des quotas mensuels (par forfait) et des limites de débit par seconde (par clé d'API).

Quotas mensuels

Chaque forfait comprend un nombre fixe de vérifications par mois calendaire :

Votre quota se remet à zéro à minuit UTC, à la date anniversaire de votre facturation. Vous pouvez consulter votre consommation actuelle sur /v1/account/usage.

Limites de débit par seconde

Une requête sur l'endpoint batch compte pour une requête par envoi de lot, pas pour une par adresse du lot.

En-têtes de limite de débit

Chaque réponse porte des en-têtes qui indiquent l'état courant de vos limites :

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

Traiter les réponses 429

Quand vous dépassez la limite de débit par seconde, vous recevez une réponse 429 Too Many Requests :

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

Le champ retry_after indique le nombre de secondes à attendre avant de réessayer.

Stratégie de backoff conseillée

Employez un backoff exponentiel avec gigue pour un traitement robuste des limites :

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;
      }
    }
  }
}

Pour une vérification en masse, passez par l'endpoint batch plutôt que d'enchaîner des requêtes individuelles dans une boucle. L'endpoint batch gère lui-même la concurrence de notre côté.

Quota épuisé

Quand votre quota mensuel est épuisé, les requêtes renvoient un 429 avec error: "quota_exceeded". Sur un forfait payant, la facturation du dépassement s'enclenche automatiquement : vous n'êtes pas bloqué. Sur le forfait Free, les requêtes sont rejetées jusqu'à la prochaine remise à zéro.

Vous recevez un e-mail de notification quand vous atteignez 80 % puis 100 % de votre quota mensuel.