Pagination et erreurs de quota des API Google : pageToken, 403 rateLimitExceeded et 429

Ce que c'est

Le guide de pagination de l'API Google Calendar illustre le schéma courant des API Discovery : on règle la taille de page avec maxResults, et on détecte la présence de pages supplémentaires en cherchant nextPageToken dans la réponse — "incomplete results can be detected by a non-empty nextPageToken field... maxResults does not guarantee the number of results on one page." L'appel suivant répète la même requête en y ajoutant pageToken, valorisé avec le nextPageToken précédent ; une réponse sans nextPageToken correspond à la dernière page. Les erreurs qui signifient « ralentir » se présentent sous deux formes documentées. Le guide des erreurs de l'API Drive décrit rateLimitExceeded ("this error occurs when the project's rate limit has been reached") et userRateLimitExceeded ("this error occurs when the per-user limit has been reached"), toutes deux renvoyées avec le statut HTTP 403 ; c'est le champ reason dans error.errors[] qui permet de les distinguer. Le même guide mentionne aussi rateLimitExceeded parmi les erreurs 429. Une troisième erreur 403, sharingRateLimitExceeded, correspond à une limite de partage ou d'envoi d'e-mails que de nouvelles tentatives rapprochées ne résolvent pas. La page des limites d'utilisation de Drive résume ainsi : "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."

Pourquoi c'est important

Un client qui ne traite que le cas 429 passera complètement à côté des erreurs de quota que Google renvoie en 403, car le statut HTTP seul ne permet pas de distinguer un accès interdit d'une limitation de débit : c'est le champ reason du corps JSON qui le fait. Comme les deux formes appellent le même remède, un client robuste doit examiner le corps de la réponse, et pas seulement le code de statut, pour décider s'il doit temporiser ou échouer immédiatement.

Comment l'appliquer

• Paginer avec pageToken/nextPageToken (ou avec le nom propre à l'API, maxResults/pageSize) et ne s'arrêter que lorsque nextPageToken est absent.
• Sur tout 403, analyser error.errors[].reason dans le corps JSON ; considérer comme réessayables exactement rateLimitExceeded et userRateLimitExceeded, et comme non réessayables les autres motifs de 403 (problème de permissions, sharingRateLimitExceeded). Comparer les motifs de façon exacte : un test de sous-chaîne sensible à la casse comme "RateLimitExceeded" in text ne reconnaît pas rateLimitExceeded, mais reconnaît sharingRateLimitExceeded.
• Sur 429, réessayer avec un backoff exponentiel, conformément aux recommandations de Google pour Drive.
• Envisager de regrouper les appels liés en lots et de demander une augmentation de quota via la console Cloud avant d'accroître le volume de requêtes ; ces deux mesures figurent explicitement parmi les remèdes cités dans la documentation d'erreurs 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))

Pièges

Réessayer indistinctement chaque 403 : en cas de véritable erreur de permissions, le client boucle silencieusement au lieu de la signaler. Supposer que maxResults a été respecté à la lettre et se fonder sur le nombre d'éléments renvoyés, plutôt que sur nextPageToken, pour décider s'il reste des pages.