Paginação e erros de cota nas APIs do Google: pageToken, 403 rateLimitExceeded e 429

O que é

O guia de paginação da Calendar API do Google mostra o padrão comum das APIs baseadas em Discovery: o tamanho da página é controlado com maxResults, e a existência de mais páginas é detectada verificando se a resposta traz nextPageToken — "incomplete results can be detected by a non-empty nextPageToken field... maxResults does not guarantee the number of results on one page." A chamada seguinte repete a mesma requisição e acrescenta pageToken com o valor do nextPageToken anterior; uma resposta sem nextPageToken é a última página. Os erros que significam "reduza o ritmo" chegam em duas formas documentadas. O guia de erros da Drive API descreve rateLimitExceeded ("this error occurs when the project's rate limit has been reached") e userRateLimitExceeded ("this error occurs when the per-user limit has been reached"). Ambos são retornados como HTTP 403, e o campo reason em error.errors[] os distingue. O mesmo guia também lista rateLimitExceeded entre os erros 429. Um terceiro 403, sharingRateLimitExceeded, é um limite de compartilhamento/e-mail que novas tentativas rápidas não resolvem. A página de limites de uso do Drive resume: "if you exceed a quota, you'll receive a 403: User rate limit exceeded... Additional rate limit checks on the Drive backend might also generate a 429: Rate limit exceeded response. If this happens, you should use an exponential backoff algorithm and try again later."

Por que importa

Um cliente que trata apenas o 429 como caso especial deixa passar por completo os erros de cota que o Google devolve com código 403, pois só o status HTTP não distingue "proibido" de "limite de taxa excedido" — quem distingue é o campo reason do corpo JSON. Como as duas formas pedem o mesmo remédio, um cliente robusto precisa inspecionar o corpo, e não apenas o código de status, para decidir se deve esperar e tentar de novo ou falhar imediatamente.

Como aplicar

• Pagine com pageToken/nextPageToken (ou com o nome específico da API, maxResults/pageSize) e pare somente quando nextPageToken estiver ausente.
• Em qualquer 403, faça o parse de error.errors[].reason no corpo JSON; trate exatamente rateLimitExceeded e userRateLimitExceeded como recuperáveis por nova tentativa, e os demais motivos de 403 (um problema de permissão, sharingRateLimitExceeded) como não recuperáveis. Compare os motivos de forma exata: um teste de substring sensível a maiúsculas e minúsculas, como "RateLimitExceeded" in text, não encontra rateLimitExceeded, mas casa com sharingRateLimitExceeded.
• Em 429, tente novamente com backoff exponencial, conforme a orientação do próprio Google para o Drive.
• Considere agrupar chamadas relacionadas em lotes e solicitar um aumento de cota pelo console do Cloud antes de aumentar o volume de requisições; ambas as medidas são listadas explicitamente como correções na documentação de erros do Google.

import random, time

RETRYABLE_403 = {"rateLimitExceeded", "userRateLimitExceeded"}

def reasons(resp):
    try:
        return {e.get("reason") for e in resp.json()["error"].get("errors", [])}
    except (ValueError, KeyError, TypeError, AttributeError):
        return set()

def call_with_backoff(fn, max_tries=5):
    for attempt in range(max_tries):
        resp = fn()
        retry = resp.status_code == 429 or (
            resp.status_code == 403 and reasons(resp) & RETRYABLE_403)
        if not retry or attempt == max_tries - 1:
            return resp  # caller decides whether to raise
        time.sleep(min(2 ** attempt + random.random(), 64))

Armadilhas

Repetir todo 403 indiscriminadamente, o que entra em loop silencioso diante de um erro de permissão genuíno em vez de exibi-lo. Presumir que maxResults foi respeitado com exatidão e usar a quantidade de itens retornados, em vez de nextPageToken, para decidir se ainda restam páginas.