Slack Web API: Paginierung und Umgang mit den methodenspezifischen Rate-Limit-Stufen

Worum es geht

Laut dem Paginierungsleitfaden von Slack "akzeptieren" cursorpaginierte Methoden die Parameter cursor und limit; paginierte Antworten enthalten ein response_metadata-Objekt auf oberster Ebene, das einen next_cursor enthält, sofern weitere Ergebnisse abzurufen sind. Der Client übergibt diesen Wert beim nächsten Aufruf als Parameter cursor. Ein leerer, null-wertiger oder fehlender next_cursor zeigt an, dass keine weiteren Ergebnisse folgen. Der Leitfaden warnt ausdrücklich davor, stattdessen aus der Anzahl der Ergebnisse auf Vollständigkeit zu schliessen. Cursor verfallen: Sie sollen nicht über Stunden oder Tage gespeichert werden, und ein veralteter oder fehlerhafter Cursor liefert invalid_cursor. Das Maximum für limit beträgt 1000, wobei sich dieser Wert ändern und je nach Methode abweichen kann; für sauberes Paging werden 100–200 empfohlen. Die Rate-Limit-Seite von Slack ordnet Methoden Stufen (Tiers) zu, grob von "1+ per minute" (Tier 1) bis "100+ per minute" (Tier 4). Hinzu kommen methodenspezifische "Special Tier"-Regeln, etwa bei chat.postMessage, das in der Regel etwa eine Nachricht pro Sekunde und Kanal erlaubt. Alle Limits gelten "per API method per workspace/team per app", also pro API-Methode, Workspace bzw. Team und App. Bei jeder HTTP-basierten API einschliesslich Incoming Webhooks führt eine Überschreitung zu "HTTP 429 Too Many Requests" und einem Retry-After-HTTP-Header, der die Sekunden bis zum nächsten möglichen Versuch angibt. Die Begrenzung gilt nur für diese Methode und diesen Workspace; andere Methoden und andere Workspaces sind nicht betroffen.

Warum es wichtig ist

Die Stufen von Slack führen dazu, dass derselbe Client bei einer Methode problemlos im Budget liegt und bei einer anderen sofort gedrosselt wird. Wer die API so behandelt, als gäbe es ein einziges globales Rate Limit, drosselt zu stark oder zu schwach. Zudem ist dokumentiert, dass das Abrufen einer ganzen grossen Liste ohne Paginierung für sich genommen strengere Limits auslöst.

So wird es angewendet

• limit immer explizit senden und nach jedem Aufruf response_metadata.next_cursor prüfen; die Schleife läuft, bis der Wert leer oder nicht vorhanden ist.
• Budgets pro Methode statt global verfolgen, da Stufen und Sonderlimits (etwa beim Senden von Nachrichten) methodenspezifisch sind.
• Bei 429 den Header Retry-After lesen und genau so lange warten, bevor dieselbe Methode für diesen Workspace erneut aufgerufen wird; andere Methoden bleiben in der Zwischenzeit nutzbar.
• Bei Massenexporten (z. B. alle Benutzer oder alle Kanäle) mit moderatem limit (100–200) paginieren, statt in einem Aufruf das Maximum anzufordern.

def list_all_users(client, limit=200):
    cursor, users = None, []
    while True:
        resp = client.users_list(limit=limit, cursor=cursor)
        users += resp["members"]
        cursor = resp.get("response_metadata", {}).get("next_cursor")
        if not cursor:
            return users

Stolpersteine

Die Paginierung abzubrechen, sobald eine Seite weniger Ergebnisse als limit liefert: Die Dokumentation von Slack nennt dies ausdrücklich kein verlässliches Zeichen für Vollständigkeit. Ebenso problematisch ist es, ein einziges Retry- bzw. Backoff-Budget für alle Web-API-Methoden anzuwenden, statt es, wie die Stufen es verlangen, pro Methode und pro Workspace zu führen.