Limites de débit
Comptées par minute glissante, par clé ou par jeton — jamais par entreprise.
| Palier | Requêtes / minute | Routes |
|---|---|---|
light | 120 | Lectures d'un seul objet et de « moi » : /users/me, /account, /presence/me, /calls/{id}/status |
medium | 60 | Tout le reste (le palier par défaut) : créer, modifier, envoyer |
heavy | 20 | Listes, médias et exports : /calls, /messages, /recordings/{id}/media… |
Chaque réponse porte trois en-têtes ; au-delà du palier, 429 rate_limited avec Retry-After en secondes.
HTTP/1.1 200 OK
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1758816060
X-Request-Id: 8d1c…
HTTP/1.1 429 Too Many Requests
Retry-After: 17
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1758816077
{"error": {"type": "rate_limited", "message": "Too many requests: 120 a minute on this route", "request_id": "8d1c…"}}X-RateLimit-Limit— le plafond du palier de cette route ;X-RateLimit-Remaining— ce qu'il vous reste dans la minute ;X-RateLimit-Reset— l'heure Unix à laquelle la fenêtre la plus ancienne se libère.- Le palier de chaque route est dans la référence (
x-rate-tier). - Les requêtes sans jeton (
/oauth/token,/oauth/authorize) sont comptées par adresse IP. - Répéter une lecture pour « voir si quelque chose a changé » est presque toujours mieux servi par un webhook ou un jeton de synchronisation.