Erreurs de l’API Rally Ligues

Quand une requête échoue, l’API répond avec un statut HTTP et un corps JSON de trois champs.

{
  "error": "Cette clé est inconnue, révoquée ou expirée.",
  "code": "UNAUTHORIZED",
  "request_id": "9f2c41d7a3b54e0c"
}

error : un message lisible, en français. Il peut changer : ne le compare jamais.
code : un code stable. Branche ta logique dessus.
request_id : l’identifiant de la requête.

Les en-têtes à lire

X-Request-Id : présent sur toute réponse, succès compris. Il vaut request_id. Recopie-le quand tu nous écris : c’est lui qui retrouve ta requête dans nos journaux. Tu peux aussi envoyer le tien, de 8 à 64 caractères parmi A-Za-z0-9_.:-.
Retry-After : le nombre de secondes à attendre avant de réessayer. Il accompagne RATE_LIMITED et LEAGUES_UNAVAILABLE.

Les codes

Code	Statut	Cause	Que faire
`INVALID_INPUT`	`400`	Requête malformée : champ manquant, valeur hors bornes, corps illisible.	Corrige la requête d’après `error`, qui nomme le champ quand il le peut.
`UNAUTHORIZED`	`401`	Clé absente, mal formée, inconnue, révoquée ou expirée.	Vérifie l’en-tête `Authorization`. Si la clé est révoquée, émets-en une nouvelle.
`FORBIDDEN`	`403`	La clé n’a pas le scope de l’opération.	Émets une clé avec le bon scope.
`ENTITLEMENT_DENIED`	`403`	L’abonnement de l’organisation ne permet pas cet accès.	Vérifie le forfait Ligues de l’organisation.
`NOT_FOUND`	`404`	L’élément n’existe pas dans l’organisation de la clé, ou la route n’existe pas.	Vérifie l’identifiant et le chemin.
`CONFLICT`	`409`	La révision envoyée est périmée, ou l’élément n’admet plus cette commande.	Relis l’élément, puis décide. Ne réessaie pas à l’aveugle.
`IDEMPOTENCY_KEY_REUSED`	`409`	Cette `Idempotency-Key` a déjà servi avec un corps différent.	Prends une clé neuve pour une nouvelle requête.
`IDEMPOTENT_REQUEST_IN_FLIGHT`	`409`	Une requête avec cette `Idempotency-Key` est encore en cours.	Réessaie dans un instant, avec la même clé.
`IDEMPOTENCY_OUTCOME_UNKNOWN`	`409`	Une requête avec cette `Idempotency-Key` s’est interrompue sans issue connue.	Relis l’élément pour savoir s’il a été créé, puis reprends avec une clé neuve.
`ROTATION_EN_COURS`	`409`	Une rotation du secret de ce point de livraison est déjà en grâce.	Attends la fin de la grâce, ou fais une rotation avec coupure immédiate.
`BODY_TOO_LARGE`	`413`	Le corps dépasse 16 Kio.	Réduis le corps. L’API ne transporte aucun fichier.
`RATE_LIMITED`	`429`	Trop de requêtes, depuis ton adresse ou avec ta clé.	Attends `Retry-After` secondes, puis reprends avec un recul exponentiel bruité.
`LEAGUES_UNAVAILABLE`	`503`	Panne passagère, ou requête plus longue que 10 secondes.	Attends `Retry-After` secondes. Après une écriture, vérifie son état avant de la répéter.
`ENTITLEMENT_UNAVAILABLE`	`503`	Le droit de l’organisation ne peut pas être vérifié pour l’instant.	Réessaie plus tard, avec un recul.
`HOLDER_UNINITIALIZED`	`503`	L’organisation n’a pas encore désigné le détenteur de son abonnement.	Demande à une personne qui gère l’organisation de le désigner.
`WEBHOOK_VAULT_UNAVAILABLE`	`503`	Les webhooks ne sont pas configurés sur ce serveur.	Écris-nous : ce n’est pas un réglage de ton organisation.

ROTATION_EN_COURS et WEBHOOK_VAULT_UNAVAILABLE viennent de la gestion des webhooks, dans l’écran Intégrations. Tu les croises rarement par l’API.

Réessayer ou pas

4xx : la requête est en cause. Corrige-la avant de la renvoyer, sauf pour 429 et IDEMPOTENT_REQUEST_IN_FLIGHT.
5xx : Rally est en cause. Réessaie avec un recul exponentiel bruité.
Sur un POST, envoie une Idempotency-Key. Un nouvel envoi rejoue alors la réponse d’origine pendant 24 heures, sans doublon.

Si tu reçois un code que ton logiciel ne connaît pas, traite-le d’après le statut HTTP.

Guide suivant : Idempotence →