My Geocode

Migration

Faire correspondre les codes d'erreur entre fournisseurs avant de changer

· 3 min de lecture · My Geocode · #gestion-des-erreurs#planification-de-migration#géocodage#erreurs-api#tests

Lors d'une migration, ce sont les réponses de succès qui retiennent le plus l'attention, puisque c'est ce que montre une démonstration et ce que vérifie généralement une première série de tests. Les réponses d'erreur reçoivent beaucoup moins d'attention, et c'est exactement l'inverse de ce qu'il faudrait, car le code de gestion des erreurs est souvent ce qui casse en premier, et de la façon la plus visible, en production lorsqu'un fournisseur change sous une application.

Chaque fournisseur de géocodage et de données de localisation a ses propres conventions pour signaler un échec : certains utilisent exclusivement les codes de statut HTTP, d'autres intègrent un champ de statut dans une réponse JSON par ailleurs en statut 200, certains distinguent « aucun résultat trouvé » et « requête invalide » avec des codes différents, et d'autres regroupent les deux dans une erreur générique. La logique de nouvelle tentative d'une application, ses messages d'erreur destinés aux utilisateurs et ses alertes de supervision sont généralement tous construits autour des conventions d'erreur d'un fournisseur précis, parfois sans que personne n'ait documenté explicitement cette dépendance.

Avant de changer de fournisseur, il vaut la peine de construire une table de correspondance explicite entre les réponses d'erreur de l'ancien fournisseur et celles du nouveau, couvrant au minimum :

  • Aucun résultat trouvé pour une requête valide mais sans correspondance, à distinguer d'une requête mal formée ou invalide
  • Limite de débit dépassée, et si la réponse indique quand réessayer
  • Les échecs d'authentification, y compris les identifiants expirés, manquants ou mal formés
  • Les erreurs côté serveur chez le fournisseur, à distinguer des erreurs de requête côté client
  • Toute valeur de statut propre au fournisseur que votre code vérifie explicitement par son nom ou son numéro

My Geocode documente ses réponses d'erreur et ses conventions de statut sur /docs/errors/, et chaque réponse contient aussi des en-têtes de quota, X-Quota-Limit, X-Quota-Used, X-Quota-Free-Remaining, X-Quota-Network-Used, X-Credits-Remaining, X-Key-IPs-Used, X-Key-IPs-Limit et X-Quota-Reset, qui couvrent une catégorie d'informations (l'état du quota et du débit) que certains fournisseurs enfouissent dans le corps des réponses d'erreur au lieu de l'exposer directement dans les en-têtes. Vérifier si votre logique actuelle de nouvelle tentative lit les informations de quota dans le corps de la réponse ou dans un en-tête est un bon point précis à ajouter à une liste de contrôle de migration, car les informations de quota fournies dans les en-têtes sont généralement plus faciles à lire sans toucher au chemin d'analyse des réponses utilisé pour les données elles-mêmes.

Une façon pratique de construire la table de correspondance consiste à déclencher délibérément chaque condition d'erreur sur l'ancien et le nouveau fournisseur dans un environnement de test, plutôt que de vous fier uniquement à la documentation, car la documentation et le comportement réel ne correspondent pas toujours exactement, chez aucun fournisseur. Envoyez une requête mal formée, épuisez délibérément un petit quota de test et envoyez une clé invalide, puis notez exactement ce que chaque fournisseur renvoie dans chaque cas.

Ce travail de correspondance des erreurs figure rarement dans le plan de projet d'une migration, car il ne produit aucune fonctionnalité visible, mais il pèse de façon disproportionnée sur le souvenir que laisse une migration. Une migration qui change proprement les réponses de succès mais laisse la gestion des erreurs défaillante génère généralement beaucoup plus de tickets d'assistance, dans les premières semaines après la bascule, qu'une migration qui n'a que partiellement réussi le scénario nominal.

Plus d'articles sur la migration