Rate Limits
Rate Limits gelten pro Endpunkt über ein rollierendes Fenster von 60 Sekunden. Jeder Endpunkt hat einen eigenen Zähler — das Limit auf einer Route beeinflusst keine andere. Bei Überschreitung liefert die API 429 Too Many Requests.
So funktioniert es
- Das Fenster beträgt 1 Minute für jeden Endpunkt.
- Limits sind pro Endpunkt isoliert —
list-boardsundsend-messagezählen getrennt. - Jede Antwort trägt Rate-Limit-Header, damit Sie sich drosseln können, bevor das Limit greift.
Response-Header
| Header | Beschreibung |
|---|---|
X-RateLimit-Limit | Maximale Anfragen für diesen Endpunkt pro Fenster. |
X-RateLimit-Remaining | Verbleibende Anfragen im aktuellen Fenster. |
X-RateLimit-Reset | Wann das aktuelle Fenster zurückgesetzt wird. |
Retry-After | Sekunden bis zum erneuten Versuch (nur bei 429). |
Limits nach Kategorie
Limits clustern in wenige Stufen. Die genaue Obergrenze hängt davon ab, wie schwer die Operation ist.
| Kategorie | Typisches Limit (pro Minute) | Beispiele |
|---|---|---|
| Reads | 50 | Boards listen, Zeile lesen, Channels listen, Benachrichtigungen listen, Bookings listen |
| Schwerere Reads | 30 | Docs-Baum, Drive-Baum, alle /workspace/*-Reads |
| Writes | 30 | Zeilen, Docs, Kommentare, Ordner anlegen/aktualisieren/löschen; Upload-Presigned-URLs |
| Schwere Writes | 20 | Markdown-Writes (Zeile, Spalte, Doc), Multipart-Upload start/finalize |
| Suche | 60 | Cross-Entity-Endpunkt /search (Docs-/Drive-Suche: 50) |
| Notification-Mutationen | 60 | Als gelesen/ungelesen markieren, löschen |
| Messaging | 100 | Channel-Nachricht senden, Direktnachricht senden |
| Export | 10 | Asynchroner Tabellenexport (am stärksten eingeschränkt) |
Repräsentative Endpunkt-Limits
| Endpunkt | Methode | Limit / 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 |
Diese Zahlen sind zum Zeitpunkt der Erstellung korrekt, können sich aber ändern. Lesen Sie die Header X-RateLimit-* zur Laufzeit statt Limits zu hardcoden — und prüfen Sie die API-Referenz für den aktuellen Wert eines bestimmten Endpunkts.
Die 429-Antwort
Wenn Sie ein Limit überschreiten, liefert der Endpunkt:
{
"statusCode": 429,
"error": "Too Many Requests",
"message": "Too many requests, please try again later",
"retryAfter": 27
}
Der Header Retry-After trägt denselben Wert (in Sekunden) wie das Body-Feld retryAfter — die Zeit bis zum Reset des Fensters.
Backoff-Hinweise
Retry-Aftereinhalten. Bei429die angegebene Sekundenzahl warten, bevor Sie erneut versuchen.- Exponentielles Backoff als Fallback. Fehlt
Retry-After(z. B. bei5xx), exponentiell warten: 1s, 2s, 4s, … X-RateLimit-Remainingbeobachten. Rechtzeitig drosseln, wenn der Wert gegen null geht, statt auf429zu warten.- Bulk-Arbeit verteilen. Beim Iterieren großer Listen oder Batch-Anlegen von Zeilen kleine Pausen zwischen Aufrufen einbauen.
- Retries begrenzen. Nach wenigen Versuchen abbrechen und den Fehler melden statt endlos zu retryen.
Siehe Fehlerbehandlung für ein vollständiges Retry-Beispiel.