Telm mesure l’API de deux manières : une limite de débit par minute (un plafond de rafale) et un quota quotidien (votre budget total pour la journée UTC). Les deux évoluent avec le plan. Chaque réponse mesurée renvoie X-Quota-Limit, X-Quota-Used et X-Quota-Reset afin que vous connaissiez toujours votre budget restant, et les deux limites renvoient 429 avec un en-tête Retry-After en cas de dépassement.
1Deux limites : débit par minute et quota quotidien
Il existe deux plafonds distincts. La limite de débit par minute plafonne le nombre de requêtes que vous pouvez effectuer au cours d’une même minute, en lissant les rafales. Le quota quotidien est votre budget global : il plafonne le nombre d’appels mesurés que vous pouvez effectuer sur l’ensemble de la journée UTC.
Ils sont indépendants. Vous pouvez atteindre la limite par minute tout en ayant encore beaucoup de quota quotidien (vous envoyez simplement trop vite), ou épuiser votre quota quotidien en étant bien en dessous de la limite par minute (vous avez consommé la journée). Les deux renvoient un statut 429, mais pour des raisons différentes — vérifiez le code d’erreur dans le corps pour les distinguer.
- Limite de débit par minute — un plafond de rafale, se réinitialise chaque minute.
- Quota quotidien — vos appels mesurés totaux pour la journée, se réinitialise à minuit UTC.
- Le quota est compté une fois par compte, partagé entre toutes vos clés.
2Quota quotidien selon le plan
Votre quota quotidien est le nombre d’appels API mesurés que vous pouvez effectuer par journée UTC, et il dépend de votre plan. Le compteur est partagé entre toutes vos clés et suit le meilleur plan parmi les groupes que vous administrez — sans abonnement payant, vous êtes sur le niveau Free.
La fenêtre est la journée calendaire UTC, si bien que votre compteur d’utilisation se réinitialise à zéro à minuit UTC. Une vérification anti-spam par lot coûte un appel par élément du lot, pas un appel pour toute la requête.
- Free — 100 appels par jour.
- Basic — 1 000 appels par jour.
- Pro — 10 000 appels par jour.
- Business — 50 000 appels par jour.
3Limite de débit par minute selon le plan
En plus du quota quotidien, chaque clé API est limitée à un nombre de requêtes par minute selon son niveau de plan. C’est une limite de lissage : elle empêche un seul client d’envoyer un énorme pic en une seconde, même quand le budget quotidien est loin d’être consommé.
Séparément, de larges plafonds par IP et par compte s’appliquent à l’ensemble de l’API pour garder la plateforme stable. En usage normal — des requêtes régulières et rythmées — vous ne les toucherez jamais ; ils ne se déclenchent que sur des rafales abusives.
- Free et Basic — 60 requêtes par minute.
- Pro — 600 requêtes par minute.
- Business — 1 800 requêtes par minute.
- Étalez les requêtes plutôt que de les envoyer toutes d’un coup.
4Lire votre budget restant
Vous n’avez jamais à deviner combien de quota il reste. Chaque réponse mesurée — succès ou échec — inclut trois en-têtes : X-Quota-Limit (votre limite quotidienne), X-Quota-Used (combien d’appels vous avez dépensés aujourd’hui), et X-Quota-Reset (le moment, en UTC, où le compteur se réinitialise).
Les endpoints de vérification anti-spam renvoient aussi les mêmes chiffres dans le corps de la réponse, sous un objet quota, afin que vous puissiez lire votre budget restant sans parser les en-têtes. Utilisez-les pour rythmer vos propres requêtes et vous prévenir avant d’être à court.
- X-Quota-Limit — votre limite d’appels quotidienne.
- X-Quota-Used — appels dépensés jusqu’ici aujourd’hui.
- X-Quota-Reset — heure de réinitialisation en UTC (RFC 3339).
- Les réponses de vérification anti-spam incluent aussi un objet quota avec les mêmes champs.
5Ce qui se passe à 429
Quand vous franchissez l’une ou l’autre limite, l’API renvoie HTTP 429 avec un en-tête Retry-After indiquant combien de secondes attendre. Pour la limite de débit par minute, Retry-After est d’environ une minute. Pour le quota quotidien, le corps porte un code daily_quota_exceeded plus votre plan, votre limite, votre nombre d’appels utilisés, l’heure de réinitialisation et un indice de mise à niveau, et Retry-After décompte jusqu’à minuit UTC.
La bonne façon de gérer un 429 est de temporiser et de réessayer après le délai Retry-After, pas de marteler l’endpoint. Les clients bien élevés lisent l’en-tête et font une pause ; les clients qui réessaient immédiatement restent simplement bloqués.
- 429 rate_limit_exceeded — vous avez envoyé trop vite ; attendez environ une minute.
- 429 daily_quota_exceeded — la journée est consommée ; attendez la réinitialisation UTC ou passez à un plan supérieur.
- Respectez toujours l’en-tête Retry-After avant de réessayer.