Paginación de la Web API de Slack y gestión de sus niveles de límite de frecuencia por método

Qué es

La guía de paginación de Slack explica que los métodos paginados con cursor "aceptan los parámetros cursor y limit" y que "las respuestas paginadas incluyen un objeto response_metadata de nivel superior que contiene un next_cursor cuando quedan resultados adicionales por obtener". El cliente devuelve ese valor como parámetro cursor en la siguiente llamada; según la guía, "un next_cursor vacío, nulo o inexistente... indica que no hay más resultados", y advierte expresamente de que no se debe deducir que la lista está completa a partir del número de resultados. Los cursores caducan, por lo que "no hay que guardar cursores durante horas o días"; un cursor obsoleto o malformado devuelve invalid_cursor. El máximo de limit es 1000, "sujeto a cambios y puede variar según el método", y para una paginación correcta se recomiendan entre 100 y 200. La página de límites de frecuencia de Slack agrupa los métodos en niveles, desde aproximadamente "1+ por minuto" (nivel 1) hasta "100+ por minuto" (nivel 4), además de reglas de "nivel especial" (Special Tier) propias de cada método, como la de chat.postMessage, que en general admite alrededor de un mensaje por segundo y por canal. Todos los límites se aplican "por método de la API, por espacio de trabajo/equipo y por aplicación". En cualquier API basada en HTTP, incluidos los incoming webhooks, superar un límite devuelve "HTTP 429 Too Many Requests... y una cabecera HTTP Retry-After con el número de segundos que faltan para poder reintentar". El límite afecta solo a ese método y a ese espacio de trabajo; los demás métodos y los demás espacios de trabajo no se ven afectados.

Por qué importa

Los niveles de Slack implican que un mismo cliente puede estar muy por debajo del límite en un método y sufrir limitación inmediata en otro; tratar la API como si tuviera un único límite global conduce a una limitación insuficiente o excesiva. Además, según la documentación, obtener de una sola vez una lista grande completa sin paginar ya provoca por sí solo límites más estrictos.

Cómo aplicarlo

• Envía siempre limit de forma explícita y comprueba response_metadata.next_cursor después de cada llamada, repitiendo el bucle hasta que esté vacío o ausente.
• Controla el presupuesto de solicitudes por método y no de forma global, ya que los niveles y los límites especiales (como el de publicación de mensajes) dependen del método.
• Ante un 429, lee Retry-After y espera exactamente ese tiempo antes de volver a llamar al mismo método en ese espacio de trabajo; mientras tanto, los demás métodos siguen siendo utilizables.
• En exportaciones masivas (por ejemplo, todos los usuarios o todos los canales), pagina con un limit moderado (100-200) en lugar de pedir el máximo en una sola llamada.

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

Trampas

Detener la paginación cuando una página devuelve menos resultados que limit; la documentación de Slack lo califica expresamente como una señal poco fiable de que la lista está completa. Aplicar un único presupuesto de reintentos o de espera creciente (backoff) a todos los métodos de la Web API, en lugar de uno por método y por espacio de trabajo, como exigen los niveles.