Erreurs et nouvelles tentatives

Les API Alkax utilisent les statuts HTTP pour le résultat principal et des corps de réponse structurés pour les détails lisibles par machine et par l’utilisateur.

Statuts courants

Statut	Signification	Action du client
400	Requête invalide ou échec de validation	Corriger la requête avant de la renvoyer
401	Identifiant absent, mal formé, invalide, expiré ou révoqué	Remplacer l’identifiant
402	Un abonnement payant est nécessaire	Activer ou renouveler l’abonnement du propriétaire du projet
403	Authentifié mais non autorisé	Vérifier les portées, les accès et l’appartenance au tenant
404	Ressource introuvable ou invisible pour ce tenant	Vérifier l’identifiant stable ; éviter les tentatives répétées à l’aveugle
409	Conflit de cycle de vie, de doublon ou d’idempotence	Lire la ressource actuelle et réconcilier les données
429	Limite de débit ou quota mensuel atteint	Respecter Retry-After, réduire l’utilisation ou choisir une formule supérieure
5xx	Erreur temporaire du serveur	Réessayer un nombre limité de fois avec un délai exponentiel

Réessayer sans risque

1. Définissez un délai d’expiration pour la requête.
2. Réessayez uniquement après une erreur réseau, une réponse 429 ou une erreur 5xx documentée comme temporaire.
3. Réutilisez la même clé d’idempotence lorsque vous réessayez la même opération logique de création.
4. Augmentez le délai de façon exponentielle en y ajoutant une variation aléatoire.
5. Arrêtez après un nombre limité de tentatives et signalez l’échec pour examen.

Ne renvoyez jamais une requête ayant reçu 400 sans la modifier. Évitez de créer une nouvelle clé d’idempotence simplement parce que la première réponse a été perdue : une seule opération souhaitée pourrait alors être exécutée deux fois.

Messages localisés

Certaines API traduisent les messages destinés aux utilisateurs selon Accept-Language. Ne faites pas dépendre la logique du programme du texte traduit. Conservez plutôt le statut, l’identifiant stable de la ressource et le code d’erreur lisible par machine.