Limiti di ritmo

Mailbeam applica due tipi di limite: quote mensili (per piano) e limiti di ritmo al secondo (per chiave API).

Quote mensili

Ogni piano include un numero fisso di verifiche per mese solare:

La tua quota si azzera a mezzanotte UTC nell'anniversario della tua fatturazione. Puoi vedere il consumo attuale su /v1/account/usage.

Limiti di ritmo al secondo

Le richieste all'endpoint in blocco contano come 1 richiesta per invio di lotto, non per ogni email del lotto.

Intestazioni del limite di ritmo

Ogni risposta include intestazioni con lo stato attuale del tuo limite:

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

Come trattare le risposte 429

Quando superi il limite di ritmo al secondo ricevi un 429 Too Many Requests:

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

Il campo retry_after indica i secondi da aspettare prima di riprovare.

Strategia di ritentativo consigliata

Usa il rallentamento esponenziale con jitter per trattare i limiti in modo solido:

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

Per verificare in volume, usa l'endpoint in blocco invece di lanciare richieste singole in un ciclo. L'endpoint in blocco gestisce la concorrenza per conto suo.

Quota esaurita

Quando la tua quota mensile si esaurisce, le richieste restituiscono un 429 con error: "quota_exceeded". Nei piani a pagamento si attiva automaticamente la fatturazione per eccedenza: non ti blocchiamo. Nel piano Free le richieste vengono rifiutate fino all'azzeramento successivo.

Ricevi avvisi via email quando arrivi all'80% e al 100% della tua quota mensile.