Limites de débit

Lisoloo applique des limites de débit par clé API sur chaque endpoint. Dépasser une limite renvoie 429 Too Many Requests avec un en-tête Retry-After et error_code: 1301 RATE_LIMIT_EXCEEDED dans le corps.

Les buckets

Endpoint	Limite	Fenêtre	Notes
POST /send	60 requêtes	par minute	Chaque requête peut toucher beaucoup de destinataires — cela compte les requêtes, pas les SMS.
GET /status/{message_id}	120 requêtes	par minute	Plafond plus élevé pour que les boucles de polling ne soient pas étranglées.
GET /balance	30 requêtes	par minute	Lecture-lourde, mais rarement nécessaire plus d’une fois par minute.
GET /health	illimité	—	Non authentifié, pas de bucket.

Les buckets sont indépendants par clé. Les clés sandbox et production ont les mêmes plafonds.

La réponse 429

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 27

{
  "success": false,
  "status_code": 429,
  "error_code": "1301",
  "message": "Rate limit exceeded",
  "retry_after": 27
}

Retry-After est en secondes (la même valeur apparaît aussi dans le corps JSON sous retry_after). Attendez au moins ce délai avant de réessayer. Réessayer plus tôt renvoie un autre 429 avec un Retry-After frais.

Respecter Retry-After

Le bon pattern de retry est attendre, puis réessayer une fois. Ne bouclez pas sur les 429 — au mieux vous gaspillez votre bucket, au pire vous déclenchez 1302 SUSPICIOUS_ACTIVITY et votre clé reçoit une suspension temporaire.

import time
import requests

def send_with_retry(payload, max_attempts=3):
    for attempt in range(max_attempts):
        r = requests.post(SEND_URL, headers=HEADERS, json=payload, timeout=10)
        if r.status_code != 429:
            return r
        delay = int(r.headers.get("Retry-After", 60))
        time.sleep(delay)
    r.raise_for_status()

async function sendWithRetry(payload, maxAttempts = 3) {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    const r = await fetch(SEND_URL, {
      method: "POST",
      headers: HEADERS,
      body: JSON.stringify(payload),
    });
    if (r.status !== 429) return r;
    const delay = parseInt(r.headers.get("Retry-After") ?? "60", 10);
    await new Promise(res => setTimeout(res, delay * 1000));
  }
  throw new Error("limité après retries");
}

Patterns de masse

Si vous envoyez à des milliers de destinataires, groupez en un seul appel plutôt que de boucler. Un seul POST /send avec un tableau to de 1 000 éléments est une seule sollicitation de limite ; 1 000 appels séparés en sont 1 000.

Plafonds stricts par requête :

• to : jusqu’à 1 000 destinataires par appel.
• scheduled_dates : jusqu’à 20 dates par appel.
• recurring_schedule : total pré-calculé ≤ 5 000 SMS futurs.

Pour des volumes plus grands, groupez en plusieurs appels espacés d’au moins 1 seconde, ou contactez votre gestionnaire de compte Bloonio pour une augmentation de plafond par marchand.

Ne pas masquer les 429 avec du parallélisme

Lancer N workers concurrents quand l’un d’eux voit un 429 multiplie le problème — vous remplissez le bucket N× plus vite. Sérialisez les retries sur la même clé, même à travers les workers.

Concurrence

La fenêtre de limite de débit se réinitialise en continu, pas sur une frontière de seconde fixe. Un pattern naïf « envoyer 60 messages à 00:00:00 » + « envoyer 60 autres à 00:01:00 » peut toujours déclencher un 429 si le burst à :01 chevauche la fenêtre. Étalez la charge sur la minute ou respectez Retry-After.

Voir aussi

• Erreurs — enveloppe complète d’erreur
• Envoyer un SMS instantané — groupement multi-destinataires