Limites de débit API Rodz : bonnes pratiques

En résumé : L’API Rodz autorise 100 requêtes par minute. Pour éviter les erreurs 429, lisez les headers de débit, implémentez un backoff exponentiel, regroupez vos appels par lots, cachez les réponses et privilégiez les webhooks au polling. Ce guide vous montre comment appliquer chaque stratégie avec des exemples en Node.js et Python.

Qu’est-ce que le rate limiting et pourquoi l’API Rodz l’utilise ?

Le rate limiting (limitation de débit) est un mécanisme qui restreint le nombre de requêtes qu’un client peut envoyer à une API sur une période donnée. C’est un standard du web moderne, présent sur pratiquement toutes les API publiques et privées.

Pourquoi imposer une telle limite ? Pour trois raisons principales. D’abord, la stabilité du service. Sans contrôle, un seul client pourrait monopoliser les ressources serveur et dégrader l’expérience de tous les autres utilisateurs. Ensuite, la protection contre les abus. Le rate limiting empêche les scripts mal configurés ou les boucles infinies de submerger l’infrastructure. Enfin, l’équité entre les clients. Chaque utilisateur de l’API Rodz dispose du même quota de base, ce qui garantit un accès homogène aux signaux d’affaires.

L’API Rodz applique une limite de 100 requêtes par minute par clé API. Cette fenêtre glissante se réinitialise progressivement. Lorsque vous dépassez cette limite, l’API renvoie un code HTTP 429 Too Many Requests accompagné d’un header Retry-After indiquant le nombre de secondes à attendre avant de renvoyer une requête.

Comprendre et respecter ces limites n’est pas une contrainte. C’est une compétence technique qui rend vos intégrations plus robustes et plus fiables. Si vous découvrez l’API Rodz, commencez par le guide de démarrage avant de poursuivre ici.

Prérequis

Avant de mettre en place les stratégies décrites dans ce guide, assurez-vous de disposer des éléments suivants :

1. Un compte Rodz actif avec un plan incluant l’accès API. Créez votre compte sur app.rodz.io si ce n’est pas encore fait.
2. Une clé API valide générée depuis votre tableau de bord. Le guide de démarrage détaille la procédure.
3. Node.js 18+ ou Python 3.9+ installé sur votre machine pour exécuter les exemples de code.
4. Une compréhension de base des requêtes HTTP, des en-têtes et des codes de statut. La référence API Rodz documente l’ensemble des endpoints et des codes d’erreur.
5. Un environnement de développement (VS Code, terminal, etc.) pour tester vos implémentations.

Comprendre les headers de rate limiting

Chaque réponse de l’API Rodz inclut trois headers qui vous informent en temps réel sur votre consommation :

Header	Description	Exemple
X-RateLimit-Limit	Nombre total de requêtes autorisées par minute	100
X-RateLimit-Remaining	Nombre de requêtes restantes dans la fenêtre en cours	73
X-RateLimit-Reset	Timestamp Unix auquel le compteur se réinitialise	1710345600

Ces headers sont votre tableau de bord en temps réel. Lisez-les systématiquement après chaque appel. Si X-RateLimit-Remaining descend en dessous d’un seuil critique (par exemple 10), ralentissez vos requêtes de manière proactive plutôt que d’attendre une erreur 429.

Voici comment lire ces headers en Node.js :

const response = await fetch('https://api.rodz.io/v1/signals/feed', {
  headers: { Authorization: 'Bearer VOTRE_CLE_API' },
});

const limit = response.headers.get('X-RateLimit-Limit');
const remaining = response.headers.get('X-RateLimit-Remaining');
const reset = response.headers.get('X-RateLimit-Reset');

console.log(`Quota : ${remaining}/${limit} — Réinitialisation : ${new Date(reset * 1000).toISOString()}`);

Et en Python :

import requests

response = requests.get(
    'https://api.rodz.io/v1/signals/feed',
    headers={'Authorization': 'Bearer VOTRE_CLE_API'}
)

limit = response.headers.get('X-RateLimit-Limit')
remaining = response.headers.get('X-RateLimit-Remaining')
reset_ts = response.headers.get('X-RateLimit-Reset')

print(f"Quota : {remaining}/{limit} — Réinitialisation : {reset_ts}")

Stratégie 1 : Implémenter le backoff exponentiel sur les réponses 429

Lorsque vous recevez une réponse 429, la pire réaction est de renvoyer immédiatement la requête. Cela aggrave le problème. La bonne approche est le backoff exponentiel : vous attendez un délai qui double à chaque tentative échouée, avec un peu d’aléatoire pour éviter que plusieurs clients ne se synchronisent.

Voici un gestionnaire complet en Node.js :

async function fetchWithBackoff(url, options, maxRetries = 5) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status !== 429) {
      return response;
    }

    const retryAfter = response.headers.get('Retry-After');
    const baseDelay = retryAfter ? parseInt(retryAfter, 10) * 1000 : Math.pow(2, attempt) * 1000;

    // Ajout d'un jitter aléatoire (0-500ms)
    const jitter = Math.random() * 500;
    const delay = baseDelay + jitter;

    console.log(`429 reçu — tentative ${attempt + 1}/${maxRetries}, attente ${Math.round(delay)}ms`);
    await new Promise((resolve) => setTimeout(resolve, delay));
  }

  throw new Error('Nombre maximum de tentatives atteint');
}

// Utilisation
const response = await fetchWithBackoff('https://api.rodz.io/v1/signals/feed', {
  headers: { Authorization: 'Bearer VOTRE_CLE_API' },
});

Et l’équivalent en Python :

import time
import random
import requests

def fetch_with_backoff(url, headers, max_retries=5):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)

        if response.status_code != 429:
            return response

        retry_after = response.headers.get('Retry-After')
        base_delay = int(retry_after) if retry_after else (2 ** attempt)

        # Jitter aléatoire entre 0 et 0.5 seconde
        jitter = random.uniform(0, 0.5)
        delay = base_delay + jitter

        print(f"429 reçu — tentative {attempt + 1}/{max_retries}, attente {delay:.1f}s")
        time.sleep(delay)

    raise Exception("Nombre maximum de tentatives atteint")

# Utilisation
response = fetch_with_backoff(
    'https://api.rodz.io/v1/signals/feed',
    headers={'Authorization': 'Bearer VOTRE_CLE_API'}
)

Le jitter aléatoire est un détail important. Sans lui, si 10 clients reçoivent un 429 en même temps, ils renverront tous leur requête au même instant, créant un nouveau pic de charge.

Stratégie 2 : Mettre en file d’attente et regrouper les requêtes

Plutôt que d’envoyer une requête à chaque fois que votre application en a besoin, regroupez-les. L’idée est simple : accumulez les requêtes dans une file d’attente et envoyez-les par lots en respectant le rythme autorisé.

class RateLimitedQueue {
  constructor(requestsPerMinute = 100) {
    this.queue = [];
    this.interval = (60 / requestsPerMinute) * 1000; // ~600ms entre chaque requête
    this.processing = false;
  }

  enqueue(url, options) {
    return new Promise((resolve, reject) => {
      this.queue.push({ url, options, resolve, reject });
      if (!this.processing) this.processQueue();
    });
  }

  async processQueue() {
    this.processing = true;

    while (this.queue.length > 0) {
      const { url, options, resolve, reject } = this.queue.shift();

      try {
        const response = await fetchWithBackoff(url, options);
        resolve(response);
      } catch (error) {
        reject(error);
      }

      // Pause entre chaque requête
      await new Promise((r) => setTimeout(r, this.interval));
    }

    this.processing = false;
  }
}

// Utilisation
const queue = new RateLimitedQueue(80); // Marge de sécurité : 80 au lieu de 100

const results = await Promise.all([
  queue.enqueue('https://api.rodz.io/v1/signals/feed?type=fundraising', { headers }),
  queue.enqueue('https://api.rodz.io/v1/signals/feed?type=hiring', { headers }),
  queue.enqueue('https://api.rodz.io/v1/signals/feed?type=merger', { headers }),
]);

Notez l’utilisation d’une marge de sécurité de 80 requêtes par minute au lieu de 100. Cette marge vous protège contre les variations d’horloge entre votre serveur et celui de l’API.

Stratégie 3 : Cacher les réponses pour éviter les appels redondants

Certaines données ne changent pas d’une seconde à l’autre. Les informations firmographiques d’une entreprise, par exemple, restent stables pendant des heures. Cacher ces réponses réduit considérablement le nombre d’appels API.

const cache = new Map();

async function fetchWithCache(url, options, ttlSeconds = 300) {
  const cacheKey = url;

  if (cache.has(cacheKey)) {
    const { data, expiry } = cache.get(cacheKey);
    if (Date.now() < expiry) {
      console.log(`Cache hit : ${url}`);
      return data;
    }
    cache.delete(cacheKey);
  }

  const response = await fetchWithBackoff(url, options);
  const data = await response.json();

  cache.set(cacheKey, {
    data,
    expiry: Date.now() + ttlSeconds * 1000,
  });

  return data;
}

// Les données d'entreprise sont cachées 5 minutes
const company = await fetchWithCache('https://api.rodz.io/v1/enrich/company?domain=example.com', { headers }, 300);

En production, remplacez ce cache en mémoire par Redis ou Memcached pour partager le cache entre plusieurs instances de votre application.

Stratégie 4 : Utiliser les webhooks au lieu du polling

Le polling (interrogation régulière de l’API) est l’ennemi du rate limiting. Si vous vérifiez toutes les 30 secondes si de nouveaux signaux sont disponibles, vous consommez 120 requêtes par heure pour une seule vérification, et souvent sans résultat.

Les webhooks inversent le flux. C’est l’API Rodz qui vous notifie lorsqu’un événement correspond à vos critères. Zéro requête gaspillée.

Consultez le guide Recevoir des signaux en temps réel : configurer les webhooks Rodz pour la mise en place complète. En résumé, vous configurez une URL de callback sur votre serveur, et l’API Rodz y envoie un POST à chaque nouveau signal.

Cette approche est plus efficace, plus réactive et consomme zéro quota de rate limiting. Réservez vos requêtes API aux opérations qui ne peuvent pas passer par un webhook : enrichissement à la demande, requêtes ad hoc, exports ponctuels.

Surveiller votre consommation API

Mettre en place les stratégies ci-dessus ne suffit pas si vous ne mesurez pas leur impact. Créez un système de monitoring simple qui trace votre consommation au fil du temps.

import time
import json
from datetime import datetime

class APIMonitor:
    def __init__(self, log_file='api_usage.json'):
        self.log_file = log_file
        self.requests_log = []

    def log_request(self, endpoint, remaining, limit):
        entry = {
            'timestamp': datetime.now().isoformat(),
            'endpoint': endpoint,
            'remaining': int(remaining),
            'limit': int(limit),
            'usage_pct': round((1 - int(remaining) / int(limit)) * 100, 1)
        }
        self.requests_log.append(entry)

        # Alerte si le quota descend sous 20 %
        if entry['usage_pct'] > 80:
            print(f"ALERTE : quota utilisé à {entry['usage_pct']}% — {remaining} requêtes restantes")

    def save(self):
        with open(self.log_file, 'w') as f:
            json.dump(self.requests_log, f, indent=2)

# Utilisation
monitor = APIMonitor()

response = requests.get(
    'https://api.rodz.io/v1/signals/feed',
    headers={'Authorization': 'Bearer VOTRE_CLE_API'}
)

monitor.log_request(
    endpoint='/signals/feed',
    remaining=response.headers.get('X-RateLimit-Remaining'),
    limit=response.headers.get('X-RateLimit-Limit')
)

Quelques indicateurs à surveiller :

• Taux d’utilisation moyen : si vous êtes constamment au-dessus de 80 %, il est temps d’optimiser ou de demander une augmentation.
• Nombre de 429 par jour : l’objectif est zéro. Chaque 429 signifie un appel raté et un délai supplémentaire.
• Répartition par endpoint : identifiez les endpoints les plus consommateurs pour cibler vos efforts de cache et de regroupement.

Quand demander une augmentation de limite

Si, malgré toutes ces optimisations, votre usage légitime dépasse régulièrement le quota de 100 requêtes par minute, il est temps de contacter l’équipe Rodz pour discuter d’une augmentation.

Préparez votre demande avec les informations suivantes :

• Votre cas d’usage détaillé : combien de signaux vous traitez, à quelle fréquence, pour quel volume de données.
• Vos métriques de consommation : montrez que vous avez optimisé votre usage (cache, webhooks, batch) avant de demander plus.
• Le quota souhaité : soyez précis. 200/min, 500/min ? Justifiez le chiffre.

L’équipe Rodz évalue chaque demande individuellement. Les augmentations sont accordées aux clients qui démontrent un usage responsable et une implémentation technique solide. Rendez-vous sur la documentation API pour accéder au formulaire de contact dédié.

Questions fréquentes

Que se passe-t-il exactement quand je dépasse la limite de 100 requêtes par minute ?

L’API renvoie un code HTTP 429 Too Many Requests avec un header Retry-After qui indique le nombre de secondes à attendre. Votre requête n’est pas traitée et les données ne sont pas retournées. Le compteur se réinitialise selon le timestamp indiqué dans X-RateLimit-Reset.

La limite s’applique-t-elle par clé API ou par compte ?

La limite de 100 requêtes par minute s’applique par clé API. Si votre compte possède plusieurs clés (par exemple une pour la production et une pour le développement), chacune dispose de son propre quota indépendant.

Les requêtes en erreur (4xx, 5xx) comptent-elles dans le quota ?

Oui. Toutes les requêtes qui atteignent le serveur sont comptabilisées, y compris celles qui génèrent une erreur 400 (Bad Request) ou 404 (Not Found). Seules les requêtes rejetées par le rate limiter lui-même (429) ne sont pas décomptées une deuxième fois.

Puis-je utiliser plusieurs clés API pour contourner la limite ?

Techniquement, c’est possible. Mais ce n’est pas recommandé et cela va à l’encontre des conditions d’utilisation. Si vous avez besoin de plus de débit, contactez l’équipe Rodz pour obtenir une augmentation officielle de votre quota. Les détails sont dans la documentation API.

Comment tester mon implémentation de backoff sans atteindre la vraie limite ?

Configurez une variable d’environnement qui force votre code à simuler des réponses 429 à intervalles réguliers. Vous pouvez aussi utiliser un mock server local (avec des outils comme WireMock ou json-server) qui renvoie systématiquement un 429 avec un header Retry-After pour valider votre logique de retry.

Le cache local est-il compatible avec le RGPD ?

Oui, tant que vous respectez les mêmes règles de conservation que pour vos autres traitements de données. Les données retournées par l’API Rodz sont des informations B2B publiquement accessibles. Assurez-vous simplement que votre TTL de cache ne conserve pas les données plus longtemps que nécessaire et que votre registre de traitements mentionne ce stockage temporaire. Consultez notre guide sur le RGPD et les signaux d’affaires pour plus de détails.

Quelle est la différence entre rate limiting et throttling ?

Le rate limiting impose une limite stricte : au-delà du seuil, les requêtes sont rejetées avec un 429. Le throttling, lui, ralentit les requêtes sans les rejeter (par exemple en ajoutant un délai de réponse). L’API Rodz utilise du rate limiting strict. Votre code doit donc gérer les rejets explicitement via le backoff exponentiel décrit dans ce guide.

Les webhooks ont-ils aussi une limite de débit ?

Les webhooks sortants (de Rodz vers votre serveur) ne sont pas soumis au même rate limiting que les requêtes API entrantes. Cependant, votre serveur doit être capable de traiter les notifications entrantes sans accumuler de retard. Si votre endpoint webhook renvoie des erreurs 5xx de manière répétée, Rodz ralentira puis suspendra les envois. Consultez le guide de configuration des webhooks pour les bonnes pratiques côté serveur.