Pourquoi le rate limiting de la Public API de n8n est essentiel
La Public API de n8n permet d’automatiser des tâches critiques : déclencher des workflows, récupérer des exécutions, ou synchroniser des données entre outils. Mais sans contrôle, un pic de requêtes peut saturer l’instance et bloquer toutes les équipes avec des erreurs 429 Too Many Requests. Ces erreurs interrompent les flux de travail et obligent les ops à relancer manuellement les processus — une perte de temps et de productivité.
Le rate limiting intégré à n8n (disponible depuis 2024) résout ce problème en :
- Limitant le nombre de requêtes par clé API, sans impacter les autres utilisateurs de l’instance.
- Fournissant des en-têtes de réponse pour adapter dynamiquement le rythme des requêtes.
- Permettant des retries sûrs grâce aux idempotency keys, évitant les doublons.
Ce guide explique comment activer, configurer et exploiter ces mécanismes pour des workflows stables.
1. Activer et configurer les limites de taux
Limites par défaut et comptage des requêtes
n8n applique deux niveaux de limites simultanées pour chaque clé API (source : F1, F2) :
- Limite globale : Nombre total de requêtes autorisées pour tous les endpoints combinés.
- Limite par endpoint : Nombre de requêtes autorisées pour un endpoint spécifique (ex:
GET /api/v1/workflows/{workflowId}).
Les requêtes sont classées en deux types, avec des limites séparées :
| Type de requête | Limite globale (60s) | Limite par endpoint (60s) |
|---|---|---|
| Lecture (GET) | 1 200 | 1 000 |
| Écriture (POST, PUT, PATCH, DELETE) | 600 | 500 |
Une requête est rejetée si elle dépasse l’une ou l’autre des deux limites. Par exemple, 1 001 requêtes GET vers le même endpoint déclenchent une erreur 429, même si la limite globale (1 200) n’est pas atteinte.
Méthodes d’activation
Vous pouvez activer ou modifier les limites via trois méthodes (source : F6) :
a. Via les paramètres n8n (interface utilisateur)- Allez dans Settings > Policies.
- Activez Enable API key rate limits.
- Configurez les limites et fenêtres (en secondes) pour All endpoints et Individual endpoints.
- Cliquez sur Enable limits.
Les modifications s’appliquent immédiatement, sans redémarrage.
b. Via l’API publiqueUtilisez l’endpoint PUT /api/v1/settings/rate-limits pour modifier les limites. Exemple de payload :
{
"globalReadLimit": 1200,
"globalReadWindowSeconds": 60,
"globalWriteLimit": 600,
"globalWriteWindowSeconds": 60,
"endpointReadLimit": 1000,
"endpointReadWindowSeconds": 60,
"endpointWriteLimit": 500,
"endpointWriteWindowSeconds": 60
}
Les requêtes vers cet endpoint comptent aussi dans les limites de taux (source : F6).
c. Via les variables d’environnement (self-hosted)Sur une instance auto-hébergée, définissez les variables suivantes avant de démarrer n8n (source : F7) :
N8N_PUBLIC_API_RATE_LIMIT_ENABLED=true
N8N_PUBLIC_API_RATE_LIMIT_GLOBAL_READ_LIMIT=1200
N8N_PUBLIC_API_RATE_LIMIT_GLOBAL_READ_WINDOW_SECONDS=60
N8N_PUBLIC_API_RATE_LIMIT_GLOBAL_WRITE_LIMIT=600
N8N_PUBLIC_API_RATE_LIMIT_GLOBAL_WRITE_WINDOW_SECONDS=60
N8N_PUBLIC_API_RATE_LIMIT_ENDPOINT_READ_LIMIT=1000
N8N_PUBLIC_API_RATE_LIMIT_ENDPOINT_READ_WINDOW_SECONDS=60
N8N_PUBLIC_API_RATE_LIMIT_ENDPOINT_WRITE_LIMIT=500
N8N_PUBLIC_API_RATE_LIMIT_ENDPOINT_WRITE_WINDOW_SECONDS=60
Attention : Les variables d’environnement écrasent les paramètres n8n. Pour modifier une limite gérée par env, vous devez redémarrer n8n (source : F7).
2. Interpréter les en-têtes de rate limiting pour éviter les 429
Lorsqu’une requête réussit, n8n inclut des en-têtes pour vous aider à rester sous les limites (source : F3) :
X-RateLimit-Limit: Nombre maximal de requêtes autorisées dans la fenêtre.X-RateLimit-Remaining: Nombre de requêtes restantes dans la fenêtre actuelle.X-RateLimit-Reset: Timestamp Unix (en secondes) de la fin de la fenêtre.
Ces en-têtes reflètent la limite la plus restrictive (globale ou par endpoint) pour la requête en cours. Ils sont absents si le rate limiting est désactivé ou si la requête n’utilise pas de clé API.
Que faire en cas de 429 ?
Une réponse 429 Too Many Requests inclut un en-tête Retry-After indiquant le nombre de secondes à attendre avant de relancer la requête (source : F4). Exemple de réponse :
HTTP/1.1 429 Too Many Requests
Retry-After: 15
Content-Type: application/json
{
"code": 429,
"message": "Too Many Requests"
}
Pour gérer une erreur 429 :
- Attendez la durée indiquée par
Retry-Afteravant de relancer la requête. Un retry trop tôt déclenche une nouvelle erreur 429. - Ajoutez un délai aléatoire (jusqu’à 5 secondes) pour éviter que plusieurs clients ne relancent en même temps (source : F5).
- Surveillez
X-RateLimit-Remaining: si la valeur est proche de 0, ralentissez jusqu’à la fin de la fenêtre (X-RateLimit-Reset). - Répartissez les requêtes sur toute la fenêtre pour éviter les pics.
3. Utiliser les idempotency keys pour des retries sûrs
Les idempotency keys garantissent qu’une requête POST retryée ne crée pas de doublon. Elles sont essentielles pour les endpoints critiques comme la création de workflows ou le retry d’exécutions (source : F10).
Comment ça marche ?
- Ajoutez un en-tête
Idempotency-Keyà votre requête POST. Exemple :Idempotency-Key: req_abc123. - La clé doit être unique par requête (ex: un UUID v4) et contenir 1 à 128 caractères ASCII visibles (sans espaces).
- n8n conserve la première réponse réussie associée à cette clé pendant 12 heures (source : F11).
- Une retry avec la même clé retourne la réponse initiale, sans relancer la requête.
Exemple d’utilisation
Requête pour créer un workflow avec une idempotency key :
curl -X POST 'https://votre-instance.n8n.cloud/api/v1/workflows' \
-H 'accept: application/json' \
-H 'X-N8N-API-KEY: votre_cle_api' \
-H 'Idempotency-Key: workflow_creation_123e4567' \
-H 'Content-Type: application/json' \
-d '{"name": "Mon workflow", "nodes": [...]}'
Si la requête échoue (ex: timeout), relancez-la avec la même clé : n8n retournera la réponse initiale si la première requête a réussi, évitant ainsi un doublon.
Limitations
- Les idempotency keys ne s’appliquent qu’aux requêtes POST (ignorées pour GET, PUT, PATCH, DELETE) (source : F12).
- Une clé identique avec un path, query string ou body différent retourne une erreur
422(source : F12). - Après 12h, la même clé relancera la requête (risque de doublon).
4. Bonnes pratiques pour les workflows n8n appelant la Public API
Configurer le batching pour rester sous les limites
Dans un workflow n8n, un node comme HTTP Request ou n8n s’exécute une fois par item. Sans contrôle, une liste de 1 000 items envoie 1 000 requêtes simultanées — bien au-delà des limites (source : F8).
Pour éviter cela, activez le batching dans les options du node :
- Items per Batch : Nombre d’items traités par lot (ex: 5).
- Batch Interval (ms) : Délai entre les lots (ex: 1 000 ms pour 1 seconde).
Exemple : 5 items/seconde = 300 requêtes/minute, sous les limites par défaut (1 000 lectures/60s ou 500 écritures/60s).
Pourquoi Retry On Fail ne résout pas les 429
L’option Retry On Fail dans les nodes n8n attend au maximum 5 secondes entre les tentatives — souvent dans la même fenêtre de rate limiting. De plus, elle relance le node pour chaque item, ce qui peut créer des doublons pour les requêtes POST (source : F9).
Solution alternative : Utilisez un node Wait pour respecter Retry-After, ou un node Loop Over Items avec un délai personnalisé.
Template n8n prêt à l’emploi
Voici un template pour un workflow n8n qui :
- Récupère des données via la Public API avec batching.
- Gère les erreurs 429 en respectant
Retry-After. - Utilise des idempotency keys pour les requêtes POST.
Téléchargez le template ici (lien vers la documentation officielle).
5. Limites et contraintes à connaître
- Variables d’environnement : Les modifications nécessitent un redémarrage de n8n pour certaines limites (ex: désactiver une limite gérée par env) (source : F7).
- En-têtes absents : Si le rate limiting est désactivé ou si la requête n’utilise pas de clé API, les en-têtes
X-RateLimit-*ne sont pas présents (source : F3). - Idempotency keys : Limitées aux endpoints POST et valables 12h seulement (source : F11, F12).
- Pas de rate limiting pour les API externes : Ce guide couvre uniquement la Public API de n8n. Pour les API tierces appelées depuis n8n, utilisez des mécanismes comme les queues ou les délais personnalisés.
Conclusion : stabilité et productivité
Configurer le rate limiting de la Public API de n8n permet d’éviter les erreurs 429 et de maintenir des workflows fluides. Voici les étapes clés :
- Activez les limites via les paramètres, l’API ou les variables d’environnement.
- Surveillez les en-têtes
X-RateLimit-RemainingetRetry-Afterpour adapter le rythme des requêtes. - Utilisez des idempotency keys pour les requêtes POST critiques.
- Configurez le batching dans vos workflows n8n pour rester sous les limites.
Pour aller plus loin, explorez nos guides sur :