Paginación y errores de cuota en las API de Google: pageToken, 403 rateLimitExceeded y 429

Qué es

La guía de paginación de la Calendar API de Google muestra el patrón habitual de las Discovery API: el tamaño de página se controla con maxResults y la existencia de más páginas se detecta comprobando si la respuesta incluye nextPageToken: "incomplete results can be detected by a non-empty nextPageToken field... maxResults does not guarantee the number of results on one page." La siguiente llamada repite la misma solicitud y añade pageToken con el valor del nextPageToken anterior; una respuesta sin nextPageToken es la última página. Los errores que significan «reduce el ritmo» llegan en dos formas documentadas. La guía de errores de la Drive API describe rateLimitExceeded ("this error occurs when the project's rate limit has been reached") y userRateLimitExceeded ("this error occurs when the per-user limit has been reached"). Ambos se devuelven como HTTP 403, y el campo reason dentro de error.errors[] los distingue. La misma guía también incluye rateLimitExceeded entre los errores 429. Existe un tercer 403, sharingRateLimitExceeded, que corresponde a un límite de uso compartido o de correo electrónico y que no se resuelve con reintentos rápidos. La página de límites de uso de Drive lo resume así: "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 qué importa

Un cliente que solo trate 429 como caso especial pasará por alto los errores de cuota que Google devuelve con código 403, porque el estado HTTP por sí solo no distingue entre «prohibido» y «límite de tasa superado»; lo que los distingue es el campo reason del cuerpo JSON. Como ambas formas requieren el mismo remedio, un cliente robusto debe inspeccionar el cuerpo, y no solo el código de estado, para decidir si aplica retroceso o falla de inmediato.

Cómo aplicarlo

• Pagina con pageToken/nextPageToken (o con el nombre propio de cada API, maxResults/pageSize) y detente solo cuando falte nextPageToken.
• Ante cualquier 403, analiza el campo error.errors[].reason del cuerpo JSON; considera reintentables únicamente rateLimitExceeded y userRateLimitExceeded, y no reintentables los demás motivos de 403 (un problema de permisos, sharingRateLimitExceeded). Compara los motivos de forma exacta: una prueba de subcadena sensible a mayúsculas como "RateLimitExceeded" in text no detecta rateLimitExceeded, pero sí coincide con sharingRateLimitExceeded.
• Ante 429, reintenta con retroceso exponencial, según la propia recomendación de Google para Drive.
• Antes de aumentar el volumen de solicitudes, valora agrupar las llamadas relacionadas en lotes y pedir un aumento de cuota desde la consola de Cloud; ambas medidas figuran explícitamente como soluciones en la documentación de errores de 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))

Trampas

Reintentar todos los 403 sin distinción: ante un error de permisos real, el cliente entrará en un bucle silencioso en lugar de mostrarlo. Suponer que maxResults se respetó exactamente y usar el número de elementos devueltos, en vez de nextPageToken, para decidir si quedan más páginas.