Les erreurs API et leur signification
Ce que signifie généralement chaque statut HTTP de l'API Didit en pratique : 401 et 403 pour les clés et les permissions, les problèmes de solde de type 402, les limites de débit 429, et comment lire le corps de l'erreur.
Lisez le corps de la réponse. Les erreurs de Didit portent un message et souvent un code de détail qui nomme le problème réel : le statut seul renseigne rarement suffisamment. 401 concerne la clé, 403 les permissions ou l'environnement, 429 la limite de débit, et une erreur de solde concerne les crédits plutôt que le code.
#Lire d'abord le corps
Le statut HTTP indique la catégorie. Le corps indique ce qui s'est passé. Presque toutes les heures de débogage évitables sur une intégration API sont passées à deviner un code de statut alors que la réponse se trouvait dans un corps de réponse qui a été ignoré.
- Une clé désactivée ou associée à la mauvaise application est la cause habituelle d'une erreur 401.
- La dernière utilisation confirme si la clé que vous pensez envoyer est bien celle qui arrive.
- Faites tourner le secret si une clé a pu fuiter : une erreur 401 vaut mieux qu'une fuite.
Consignez le corps complet de l'erreur (statut, en-têtes et charge utile) pour chaque appel échoué, dans chaque environnement. Vous en aurez besoin, et il est bien plus difficile de le reconstituer plus tard.
#Ce que signifie généralement chaque statut
| Statut | Cause habituelle |
|---|---|
| 400 | Une requête malformée : un champ requis manquant, une valeur d'énumération incorrecte, un objet imbriqué de forme erronée |
| 401 | L'authentification a échoué. L'en-tête x-api-key est manquant, malformé, ou n'est pas une clé valide |
| 403 | Authentifié mais non autorisé. Mauvais environnement, permission absente de votre clé, ou fonctionnalité non activée sur votre compte |
| 404 | La ressource n'existe pas, ou existe sous une application différente de celle de la clé utilisée |
| 409 | Un conflit avec l'état existant, par exemple une action déjà effectuée |
| 422 | La requête était bien formée mais les valeurs ne sont pas acceptables : un échec de validation plutôt que de syntaxe |
| 429 | Limite de débit atteinte. Voir ci-dessous |
| 5xx | Un problème du côté de Didit. Réessayez avec un backoff, et consultez status.didit.me |
#401 contre 403 : la distinction qui fait gagner du temps
401 signifie que la clé n'a pas du tout été acceptée. Vérifiez que vous envoyez bien x-api-key, que la valeur ne contient pas d'espace ou de guillemet superflu, et que vous n'avez pas collé un secret de signature de webhook à la place de la clé API : ce sont deux choses différentes et l'erreur est fréquente.
403 signifie que la clé est valide mais que cet appel n'est pas autorisé. Trois causes, dans l'ordre :
- Environnement incorrect. Les champs réservés au sandbox (comme
sandbox_scenario) sont rejetés sur une application en production, et inversement. La production et le sandbox sont des applications distinctes avec des clés distinctes. - Permission manquante. Certaines opérations nécessitent des permissions que votre clé ou votre rôle ne possède pas. Si vous avez besoin de droits de création et de gestion de session que vous n'avez pas, c'est une demande à adresser au support plutôt qu'une correction de code.
- Fonctionnalité non activée. Certaines capacités sont provisionnées par organisation. Une erreur 403 sur une fonctionnalité que vous pensez posséder mérite d'être signalée avant de réécrire l'appel.
Il n'existe aucun moyen intégré de distinguer une clé sandbox d'une clé de production en la regardant, donc stockez-les sous des noms clairement distincts dans votre gestionnaire de secrets, et ne laissez jamais une seule variable d'environnement contenir "la clé actuelle, quelle qu'elle soit". Une clé de production dans un environnement de test dépense de vrais crédits.
#Une erreur 404 qui ne devrait pas se produire
Si une session ou un workflow renvoie une erreur 404 alors que vous êtes certain qu'elle existe, la réponse habituelle est qu'elle existe sous une application différente de celle de la clé avec laquelle vous vous êtes authentifié. Les ressources sont associées à leur application ; une clé de l'application A ne peut pas voir les sessions de l'application B.
#Erreurs de solde et de crédits
Un appel qui échoue parce qu'il n'y a pas assez de crédits n'est pas un problème de code. Le workflow contient une fonctionnalité payante et votre solde ne la couvre pas. C'est de loin le signalement "l'API est cassée" le plus fréquent, et la cause est presque toujours le white label, l'AML ou le NFC dans un workflow censé être gratuit. Voir corriger une erreur de crédits insuffisants.
#Limite de débit 429
Les limites s'appliquent par identifiant (votre x-api-key, ou votre IP client si aucune clé n'est envoyée) avec un compteur indépendant par périmètre sur une fenêtre glissante de 60 secondes.
Valeurs par défaut globales :
| Périmètre | Méthodes | Limite |
|---|---|---|
| Lectures génériques | GET | 600 / min |
| Écritures génériques | POST, PATCH, DELETE | 300 / min |
Certains endpoints à fort impact ont des limites plus strictes en plus de la limite globale, et le premier périmètre à dépasser son compteur est celui qui renvoie une erreur 429. Table complète : limitation de débit.
Gérez l'erreur 429 avec un backoff exponentiel et du jitter. Une boucle de nouvelle tentative trop rapprochée contre une limite de débit aggrave le problème et peut vous maintenir limité indéfiniment.
Les tâches par lots sont la source habituelle d'une erreur 429 : un import nocturne qui déclenche plusieurs centaines de créations en quelques secondes. Répartissez le travail plutôt que d'augmenter la concurrence jusqu'à ce que l'erreur cesse.
#Codes de détail au niveau des fonctionnalités
Au-delà des statuts HTTP, chaque contrôle renvoie ses propres codes de détail pour les problèmes côté fournisseur : par exemple une intégration de registre qui n'a pas accès à un produit particulier dans un pays donné. Lorsque vous en recevez un, le code nomme précisément la situation, donc citez-le lorsque vous posez une question à ce sujet.
Si une réponse omet un code de détail que vous attendiez du catalogue, cela mérite d'être signalé plutôt que contourné : un code manquant est une vraie lacune, et il rend le même problème plus difficile pour la personne suivante.
#Les réponses vides ne sont pas des succès
Un contrôle adossé à un fournisseur qui renvoie un corps vide n'équivaut pas à un résultat propre. Traitez "aucune donnée" comme un cas à part dans votre code plutôt que de le faire correspondre à une réussite, en particulier pour la validation de base de données et le criblage de portefeuille, où un service non provisionné et une véritable absence de correspondance peuvent se ressembler de l'extérieur.
#Tester les chemins d'erreur
Le sandbox force des échecs spécifiques de façon déterministe, ce qui est la seule façon raisonnable de tester votre gestion des erreurs. Voir tester en sandbox.