401, 403, 429 ou 503 : diagnostiquer une erreur d’API

Recueillir les faits avant de modifier le client

Notez la méthode, le point d’accès, le statut, l’heure et l’identifiant de requête disponible. Lisez le corps d’erreur et les en-têtes pertinents. Identifiez aussi l’émetteur : application API, passerelle ou proxy de protection peuvent refuser une requête pour des raisons différentes.

Reproduisez avec une seule requête minimale. Comparez-la à un appel qui fonctionne et ne changez qu’un élément à la fois. Retirez Authorization, cookies et URL contenant des secrets des captures et journaux ; l’identifiant de requête est généralement plus sûr à transmettre.

Comprendre avant de réessayer

Pour 401, vérifiez les identifiants et le mécanisme d’authentification. Pour 403, examinez les permissions et la ressource demandée. Répéter une requête interdite ne corrige généralement rien.

Examiner 401 et 403 séparément

Pour 401, vérifiez la présence, l’expiration et le schéma de l’identifiant, par exemple Bearer. Une réponse 401 conforme comporte WWW-Authenticate. Si l’API propose un renouvellement, renouvelez une fois et réessayez une fois. Une boucle infinie ne corrige pas un mauvais identifiant.

Pour 403, examinez le rôle du compte, la ressource et les autorisations API. Un utilisateur peut lire sans pouvoir modifier. Un proxy peut également bloquer une IP ou une zone géographique. Générer un autre jeton ne donne pas nécessairement le droit manquant : suivez le corps d’erreur et les règles du service.

Encadrer les nouvelles tentatives

Pour 429 ou 503, respectez Retry-After s’il est fourni et espacez les tentatives. Réessayez seulement si répéter l’opération est sûr : une écriture ayant expiré peut déjà être effective. Conservez les identifiants de requête, jamais les secrets.

Interpréter Retry-After

429 peut concerner un utilisateur, une IP ou un quota partagé. Dans la réponse illustrative ci-dessous, Retry-After: 30 demande d’attendre 30 secondes. Le champ peut aussi contenir une date HTTP ; un véritable client doit gérer cette forme.

Réduisez la concurrence et coordonnez les relances des workers partageant une même limite. Pour 503, examinez aussi l’état du service et de la passerelle. Respectez Retry-After ; sinon, utilisez des délais croissants avec dispersion aléatoire et une durée totale limitée. Une multiplication des relances peut aggraver une surcharge.

HTTP/1.1 429 Too Many Requests
Retry-After: 30

Une absence de réponse ne prouve pas l’échec de l’opération

Une demande de paiement ou de création de tâche peut expirer après son acceptation. La répéter peut créer un doublon même sans réception du premier résultat. Pour les écritures, utilisez le mécanisme d’idempotence documenté ou vérifiez l’état avant de soumettre à nouveau. N’inventez pas un en-tête non pris en charge.

Un client pratique distingue les problèmes permanents d’autorisation des incidents temporaires, limite les tentatives et conserve la raison de l’arrêt. Répéter GET est généralement plus simple que POST, mais le contrat de l’API décide. Transmettez heure, point d’accès, statut et identifiant de requête sans les secrets.