Référence
Limites de débit
Les limites protègent l'API des déferlements, pas des revendeurs normaux. Chaque compte a une limite par minute qui augmente avec ses dépenses, et quelques limites ciblées couvrent les actions lourdes. Les règles propres à une commande, comme l'attente de la recharge, renvoient leur propre code d'erreur au lieu d'un 429.
Couches de limitation
Par IP
20 000 requêtes / minute / adresse IP
Appliqué avant la validation de la clé afin de borner l'énumération par force brute des clés. Partagé entre toutes les clés derrière la même IP. La valeur par défaut est définie globalement et n'est pas configurable par l'utilisateur.
Fenêtre partagée du compte
120–2 400 requêtes / 60 secondes glissantes
Toutes les clés API actives d’un compte consomment le même compteur. La grille fixe des dépenses réussies à vie fournit la limite, sauf dérogation RPM directe.
Propre à l’action
Dépend de l’action
Services, catalog, cancel, refill et les actions webhook ont leurs propres limites ciblées, indiquées ci-dessous. Elles s'ajoutent à la limite du compte ; elles ne la remplacent pas.
Limites par action
Ces limites comptent par compte et par minute. Un 429 provenant de l'une d'elles indique action dans X-RateLimit-DeniedBy. Cancel et refill comptent les ID de commande, pas les requêtes : un appel pour 10 commandes consomme 10 des ID dont vous disposez par minute. Un cancel ou un refill avec plus d'ID que cela, jusqu'à 100, passe s'il est votre premier appel de la minute et consomme toute la minute.
| Action | Par minute | Ce qui est compté |
|---|---|---|
| services | 10 | Requêtes |
| catalog | 30 | Requêtes |
| cancel | 30 | ID de commande |
| refill | 30 | ID de commande |
| webhook.* | 10 | Requêtes |
Grille des dépenses réussies à vie
La limite de votre compte suit vos dépenses réussies cumulées à vie ; un palier supérieur débloque aussitôt une limite plus élevée. Le plafond par IP de 20 000 requêtes par minute s'applique avant la vérification de la clé. Un administrateur peut définir une limite directe pour un compte, jusqu'à 10 000. Le palier de votre compte figure dans l'en-tête X-RateLimit-Tier et sur votre page API.
| Palier | Dépenses à vie minimales | Requêtes / minute |
|---|---|---|
| 0 | 0 $ | 120 |
| 1 | 10 $ | 300 |
| 2 | 50 $ | 600 |
| 3 | 100 $ | 900 |
| 4 | 500 $ | 1 200 |
| 5 | 1 000 $ | 1 800 |
| 6 | 2 500 $ | 2 400 |
En-têtes de réponse
En-têtes de réponse
X-RateLimit-Limit- Sur les réponses normales, la limite effective de requêtes par minute partagée par le compte. Sur un 429, la limite signalée par la couche de refus.
X-RateLimit-Remaining- Sur les réponses normales, les requêtes restantes dans la fenêtre partagée du compte. Sur un 429, la valeur restante signalée par la couche de refus.
X-RateLimit-Reset- Nombre relatif de secondes avant la réinitialisation de la fenêtre signalée ; ce n’est pas un horodatage Unix.
X-RateLimit-Tier- Le palier acquis par les dépenses réussies à vie (0–6). Une dérogation RPM personnalisée ne modifie pas cette valeur.
X-RateLimit-DeniedBy- Envoyé sur les réponses 429 lorsqu’un limiteur nommé refuse l’appel : "ip", "api_requests_per_minute" ou "action".
Retry-After- Pour une réponse 429 ou 503 réessayable, attendez au moins le nombre de secondes indiqué par Retry-After avant de réessayer. Pour action=add, réutilisez la même clé d’idempotence après l’attente.
Gérer les réponses 429
Attendez selon Retry-After lorsqu'il est présent.
Sinon, attendez les secondes de X-RateLimit-Reset. Les deux valeurs sont des délais relatifs, pas des heures d'horloge ; ajoutez une variation aléatoire avant de réessayer.Lisez X-RateLimit-DeniedBy.
Il nomme la limite qui a refusé l'appel. Changer de clé n'aide pas, car les limites de compte, d'IP et d'action sont partagées.Utilisez des webhooks plutôt que l'interrogation.
Les webhooks arrivent au moins une fois : rendez donc votre gestionnaire idempotent et utilisezaction=statuspour vérifier tout ce qui est important.Regroupez quand vous le pouvez.
Status, cancel et refill acceptent jusqu'à 100 ID dans une requête ; le décompte des ID de commande s'applique toujours à cancel et refill.