Limites de débit

Les limites de débit s'appliquent par endpoint sur une fenêtre glissante de 60 secondes. Chaque endpoint a son propre compteur, donc atteindre la limite sur une route n'affecte jamais une autre. Dépasser une limite renvoie 429 Too Many Requests.

Fonctionnement

• La fenêtre est de 1 minute pour chaque endpoint.
• Les limites sont isolées par endpoint — list-boards et send-message comptent séparément.
• Chaque réponse porte des en-têtes de limite de débit pour que vous puissiez vous réguler avant d'atteindre le plafond.

En-têtes de réponse

En-tête	Description
X-RateLimit-Limit	Nombre maximum de requêtes autorisées pour cet endpoint par fenêtre.
X-RateLimit-Remaining	Requêtes restantes dans la fenêtre en cours.
X-RateLimit-Reset	Moment de réinitialisation de la fenêtre en cours.
Retry-After	Secondes à attendre avant de réessayer (envoyé sur 429 uniquement).

Limites par catégorie

Les limites se regroupent en quelques niveaux. Le plafond exact dépend de la lourdeur de l'opération.

Catégorie	Limite typique (par minute)	Exemples
Lectures	50	Lister boards, obtenir une ligne, lister channels, lister notifications, lister bookings
Lectures plus lourdes	30	Arbre docs, arbre drive, toutes les lectures /workspace/*
Écritures	30	Créer/mettre à jour/supprimer lignes, docs, commentaires, dossiers ; URLs d'upload pré-signées
Écritures lourdes	20	Écritures Markdown (ligne, colonne, doc), démarrage/finalisation d'upload multipart
Search	60	L'endpoint cross-entité /search (docs/drive search sont à 50)
Mutations de notifications	60	Marquer lu/non lu, supprimer
Messagerie	100	Envoyer un message de channel, envoyer un message direct
Export	10	Export de table async (l'endpoint le plus restreint)

Limites d'endpoints représentatives

Endpoint	Méthode	Limite / min
/board/list-boards	GET	50
/board/{boardId}/table/{tableId}/rows	GET	50
/board/{boardId}/table/{tableId}/row	POST	30
/board/{boardId}/table/{tableId}/row/{rowId}/md	POST	20
/board/{boardId}/table/{tableId}/export	POST	10
/docs/tree	GET	30
/docs/{docId}/md	POST	20
/drive/files/upload/multipart/start	POST	20
/search	GET	60
/notifications	GET	50
/notifications/{notificationId}	PATCH / DELETE	60
/workspace/info	GET	30
/chat/channels	GET	50
/chat/channel/{channelId}/send-message	POST	100

note

Ces chiffres sont exacts au moment de la rédaction mais peuvent changer. Lisez toujours les en-têtes X-RateLimit-* à l'exécution plutôt que de coder les limites en dur — et consultez la Référence de l'API pour la valeur actuelle sur un endpoint spécifique.

La réponse 429

Lorsque vous dépassez une limite, l'endpoint renvoie :

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Too many requests, please try again later",
  "retryAfter": 27
}

L'en-tête Retry-After porte la même valeur (en secondes) que le champ retryAfter du corps — le temps jusqu'à la réinitialisation de la fenêtre.

Conseils de backoff

• Honorez Retry-After. Sur un 429, attendez le nombre de secondes qu'il spécifie avant de réessayer.
• Utilisez un backoff exponentiel en secours. Si aucun Retry-After n'est présent (par exemple sur un 5xx), reculez de façon exponentielle : 1s, 2s, 4s, …
• Surveillez X-RateLimit-Remaining. Ralentissez de façon proactive lorsqu'il approche de zéro au lieu d'attendre un 429.
• Étalez le travail en masse. Lorsque vous parcourez de grandes listes ou créez des lignes par lots, ajoutez un petit délai entre les appels pour rester sous le plafond par minute.
• Plafonnez les retries. Abandonnez après quelques tentatives et remontez l'erreur plutôt que de réessayer indéfiniment.

Voir Gestion des erreurs pour un exemple de retry complet.