Une réponse d'erreur n'est pas une note de bas de page d'une API : elle fait partie du contrat sur lequel chaque intégration s'appuie, tout autant qu'une réponse réussie. Nous avons standardisé le format d'erreur sur tous les endpoints natifs de My Geocode, de sorte qu'un échec a le même aspect quelle que soit la partie de l'API qui l'a produit.
Qu'une requête échoue à cause d'un paramètre manquant, d'une clé non valide, d'un quota épuisé ou d'une coordonnée mal formée, la réponse suit une structure unique et prévisible. Cette cohérence signifie que le code de gestion des erreurs écrit une fois, pour un endpoint, fonctionne de la même façon avec tous les autres endpoints natifs, sans logique de traitement distincte pour chacun.
Les échecs liés au quota méritent une mention particulière, car ce sont les plus fréquents pour une intégration active. Lorsqu'une requête dépasserait le quota d'une clé ou d'un réseau, la réponse l'indique clairement, et les en-têtes de quota déjà présents sur chaque réponse, X-Quota-Limit, X-Quota-Used, X-Quota-Free-Remaining et les autres, vous indiquent exactement la marge disponible avant la requête qui a échoué. Grâce à cette combinaison, un client peut distinguer un problème de quota d'un problème d'authentification ou d'une requête incorrecte à partir de la seule réponse, sans deviner.
Les hôtes compatibles sont une exception délibérée à cette standardisation, et pour une bonne raison. Leur raison d'être est de reproduire exactement le format de requête et de réponse d'un autre fournisseur, y compris l'aspect des erreurs. Une requête au format Bing Maps REST Services qui échoue reçoit toujours une erreur au format d'erreur propre à Bing, car reproduire ce format avec précision, en cas de succès comme d'échec, est tout l'intérêt d'un hôte compatible (drop-in). Y standardiser les erreurs casserait justement la compatibilité que l'hôte est censé offrir.
Pour tout ce qui est construit sur nos endpoints natifs, ce format plus clair devrait rendre la gestion des erreurs nettement plus simple à écrire et à maintenir. Une seule routine d'analyse, un seul ensemble de champs attendus, et un comportement cohérent sur /v1/forward, /v1/reverse, /v1/ip, /v1/timezone, /v1/elevation, /v1/autocomplete comme sur /v1/postcode.
La documentation complète du format d'erreur, avec les noms de champs et les causes fréquentes, est disponible sur /docs/errors/. Si votre intégration comporte actuellement des branches de gestion d'erreurs distinctes pour différents endpoints natifs, c'est le bon moment pour les simplifier en une seule.