Gestion des limites de requêtes

Un 429 signifie qu'une partie de votre code envoie des requêtes plus vite que nécessaire, et il n'atteint un client que lorsque ce job et votre checkout partagent le même quota. Le tableau des quotas se trouve dans Limites de requêtes ; cette page vous aide à ne pas atteindre ces limites.

Trois plafonds vérifiés dans l'ordre

Chaque requête authentifiée passe par trois compteurs indépendants, chacun calculé sur une fenêtre de 60 secondes. Le premier compteur plein interrompt la requête et son nom apparaît dans le corps de la réponse.

Deux conséquences sont à retenir. Toutes les clés puisent dans le même budget d'équipe : répartir le trafic entre plusieurs clés n'ajoute donc aucune marge. Les plafonds par endpoint sont aussi les premiers touchés lors d'un pic : une boucle sur les paiements déclenche endpoint bien avant team. Sur Enterprise, aucun des trois n'est compté.

Les requêtes envoyées sans clé reconnue sont limitées à 30 par minute et par IP, avec type à ip. C'est la limite que vous rencontrez lorsqu'une clé est incorrecte, et non simplement très sollicitée.

Lisez le plafond, ne l'écrivez pas en dur

Chaque réponse indique la consommation actuelle de votre équipe. Ces trois en-têtes font foi et leurs valeurs évoluent avec votre plan.

X-RateLimit-Limit: 360
X-RateLimit-Remaining: 357
X-RateLimit-Reset: 1748083260

Si l'un de vos jobs approche de la limite, faites-lui lire X-RateLimit-Remaining et ralentir avant d'être bloqué. Réagir à l'en-tête ne coûte rien. Réagir au 429 ajoute un aller-retour et un délai que vous n'avez pas choisi.

Le plafond des écritures de payout

Les écritures de payout ont un plafond dédié, en plus des compteurs ci-dessus : POST /transfers, POST /transfers/batch, POST /accounts/{id}/payouts, POST /beneficiaries, POST /beneficiaries/{id}/receivables et POST /beneficiaries/{id}/receivables/{receivable}/settle partagent un plafond fixé à 20 requêtes par minute, par équipe et par environnement, quel que soit votre plan. Une boucle qui crée un bénéficiaire puis le paie compte deux fois.

type indique le plafond atteint. Chaque 429 contient retry_after en secondes, et l'en-tête Retry-After.

Un 429 n'est pas un plafond : POST /events/{id}/resend le renvoie, avec error_code: event_resend_cooldown, quand l'événement a été renvoyé il y a moins de 5 minutes. Attendre quelques secondes n'y change rien : voir Un 429 qui n'est pas une limitation.

Respectez le délai indiqué

Le délai se trouve dans la réponse. L'estimer vous fait soit attendre inutilement, soit recevoir un second 429.

import { WajubRateLimitError } from '@wajub/node';

export async function withRateLimitRetry(fn, maxAttempts = 5) {
  for (let attempt = 1; ; attempt++) {
    try {
      return await fn();
    } catch (err) {
      if (!(err instanceof WajubRateLimitError) || attempt >= maxAttempts) throw err;

      const seconds = err.retryAfter ?? 2 ** attempt;
      await new Promise((r) => setTimeout(r, seconds * 1000 + Math.random() * 500));
    }
  }
}

Le SDK lit Retry-After et place sa valeur dans err.retryAfter. La part d'aléa est importante lorsque plusieurs workers ont été limités en même temps. Sans elle, ils reprennent tous au même instant et remplissent de nouveau le compteur qu'ils attendaient.

Isolez les traitements par lots du checkout

Les opérations de rapprochement, les exports de règlements et toute boucle sur les transferts ou les bénéficiaires provoquent souvent des réponses 429. Ce sont aussi les traitements les plus simples à corriger, car personne n'attend leur résultat.

Une clé distincte ne protège pas le checkout à elle seule : toutes les clés puisent dans le même budget d'équipe et les mêmes plafonds par endpoint. Elle vous permet de révoquer le job sans toucher au checkout. Seul l'espacement des appels empêche un export incontrôlé de consommer les requêtes dont votre checkout a besoin.

Lorsque vous avez réellement besoin de plus

Si le plafond limite du trafic réel et non une boucle, c'est le nombre de requêtes par minute de votre plan qui doit évoluer. Contactez le support en indiquant l'endpoint, le profil de trafic et le volume attendu. Augmenter la limite d'un job qui interroge chaque paiement toutes les cinq secondes ne fait que repousser le problème.