Rate limits
Écrivez le client à partir des en-têtes, pas d’un chiffre
Les quotas varient selon le plan et évoluent. La forme de la politique, non : lisez les en-têtes, temporisez avec gigue, et utilisez le chemin groupé pour le travail en masse.
- Appliqué par
- Organisation
- Signalé par
- En-têtes de réponse
- Résolution
- Compté séparément
Definition
Comment les limites de débit de l’API sont-elles appliquées ?
Les limites s’appliquent par organisation et par classe de point de terminaison, et sont communiquées à chaque réponse par des en-têtes donnant la limite, l’allocation restante et l’heure de réinitialisation. La résolution publique de passeport est comptée séparément de votre quota, car une rafale de scans ne doit pas consommer le budget d’un pipeline d’émission.
A client written against the headers keeps working when a quota changes. A client written against a number from a documentation page does not, and fails at the least convenient moment.
Classes
Tous les points de terminaison ne sont pas comptés de la même façon
| Class | Example | How it is governed |
|---|---|---|
| Public resolution | A consumer scanning a data carrier | Caching and edge capacity, not your quota |
| Read | Fetching a passport or an object history | Account quota, generous, cache-friendly |
| Write | Issuing a passport, appending an event | Account quota, lower ceiling than read |
| Bulk | Back catalogue import, historic event backfill | Asynchronous job with its own concurrency limit |
| Credential operations | Issuing or verifying a signed claim | Metered separately; cryptographic work is not free |
En-têtes
Ce que chaque réponse vous apprend
RateLimit-Limit: the ceiling for this endpoint class
RateLimit-Remaining: what is left in the current window
RateLimit-Reset: seconds until the window resets
Retry-After: present on 429 — honour this first
# Back off with jitter. A fixed interval across many workers
# turns one brief limit into a sustained one.
const delay = Math.min(2 ** attempt * base, ceiling);
await sleep(delay * (0.5 + Math.random() / 2));Conception du client
Ce que fait un client bien élevé
Lit les en-têtes
S’adapte à l’allocation en cours au lieu de supposer un chiffre documenté.
Temporise avec gigue
Délai aléatoire, pour que des workers parallèles ne réessaient pas en cadence.
Utilise la voie en masse
La reprise d’historique passe par le mode groupé, pas par une boucle sur un point de terminaison unitaire.
Sépare les pipelines
Émission et reporting sur des clés distinctes, si bien que l’une ne peut pas affamer l’autre.
Plafonne ses reprises
Abandonne et remonte l’échec plutôt que de réessayer indéfiniment.
Alerte avant le plafond
Des alertes sur l’allocation restante, pour que le premier signe ne soit pas un 429 en production.
Réponses
Questions fréquentes
Quelles sont les limites réelles ?
Elles dépendent de votre formule et de la classe du point de terminaison, et figurent dans votre contrat plutôt qu’ici. Un chiffre publié serait périmé au bout d’une version, et un intégrateur qui dimensionnerait dessus découvrirait la vraie limite en production. Lisez plutôt les en-têtes : ils sont toujours à jour.
Comment un client doit-il réagir à un 429 ?
Respectez `Retry-After` s’il est présent, sinon temporisez de façon exponentielle avec gigue, et plafonnez le nombre de tentatives. Réessayer immédiatement, ou à intervalle fixe sur de nombreux workers, transforme une limitation brève en limitation durable — la ruée qui fait d’un petit problème une panne.
La résolution publique d’un passeport est-elle limitée de la même façon ?
Non. La résolution est publique, cacheable et attendue par rafales : elle est donc régie par le cache et la capacité en périphérie, pas par votre quota. Un produit qui devient viral ne doit pas consommer le quota dont dépend votre pipeline d’émission, d’où deux chemins comptés séparément.
Comment charger un important historique de catalogue ?
Par le chemin d’import en masse, et non en bouclant sur le point de terminaison de ressource unique. Le mode masse est conçu pour le débit et s’exécute de façon asynchrone avec un travail que vous interrogez ; le point de terminaison unitaire est conçu pour la latence. Se tromper de chemin est la cause la plus fréquente de limitation de débit auto-infligée.
Les limites s’appliquent-elles par clé ou par organisation ?
Par organisation, avec une visibilité par clé. Cela compte quand vous limitez les clés par service : un service qui se comporte mal peut consommer le budget commun, et la ventilation par clé est ce qui vous permet de le trouver vite plutôt que par élimination.
Next step
Donnez-nous vos volumes avant de construire
Taille du catalogue, cadence d’émission et pic saisonnier. Nous préférons dimensionner correctement plutôt que vous laisser découvrir un plafond en production.