Paginação da Web API do Slack e tratamento dos níveis de rate limit por método

O que é

Segundo o guia de paginação do Slack, os métodos paginados por cursor funcionam assim: "accept cursor and limit parameters" e "paginated responses include a top-level response_metadata object that includes a next_cursor when there are additional results to be retrieved." O cliente devolve esse valor no parâmetro cursor da chamada seguinte; "an empty, null, or non-existent next_cursor... indicates no further results," e o guia alerta expressamente contra deduzir que a listagem terminou a partir da quantidade de resultados. Os cursores expiram, por isso "do not persist cursors for hours or days"; um cursor vencido ou malformado retorna invalid_cursor. O valor máximo de limit é 1000, "subject to change and may vary per method", e o recomendado para uma paginação bem-comportada é entre 100 e 200. A página de rate limits do Slack agrupa os métodos em níveis (tiers), de aproximadamente "1+ per minute" (Tier 1) até "100+ per minute" (Tier 4), além de regras de "Special Tier" por método, como a de chat.postMessage, que em geral permite cerca de uma mensagem por segundo por canal. Tudo isso é aplicado "per API method per workspace/team per app." Em qualquer API baseada em HTTP, incluindo incoming webhooks, exceder um limite resulta em "HTTP 429 Too Many Requests... and a Retry-After HTTP header containing the number of seconds until you can retry", restrito àquele método e àquele workspace; os demais métodos e workspaces não são afetados.

Por que importa

Os níveis do Slack fazem com que o mesmo cliente possa estar bem dentro do orçamento em um método e ser limitado de imediato em outro; tratar a API como se tivesse um único rate limit global leva a throttling insuficiente ou excessivo. Segundo a documentação, buscar uma lista grande inteira sem paginação também atrai, por si só, limites mais rígidos.

Como aplicar

• Envie sempre limit de forma explícita e verifique response_metadata.next_cursor após cada chamada, repetindo o laço até que o valor esteja vazio ou ausente.
• Controle os orçamentos por método, e não de forma global, já que os níveis e os limites especiais (como o de postagem de mensagens) são específicos de cada método.
• Ao receber 429, leia Retry-After e espere exatamente esse tempo antes de chamar de novo o mesmo método naquele workspace; enquanto isso, os outros métodos continuam utilizáveis.
• Em exportações em massa (por exemplo, todos os usuários ou todos os canais), pagine com um limit moderado (100-200) em vez de pedir o máximo em uma única chamada.

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

Armadilhas

Interromper a paginação quando uma página retorna menos resultados que limit, sinal que a documentação do Slack classifica expressamente como não confiável para indicar o fim da listagem. Aplicar um único orçamento de retry/backoff a todos os métodos da Web API, em vez de um por método e por workspace, como os níveis exigem.