Une API sans résultat et une API en erreur demandent deux traitements différents. Une recherche réussie peut ne retourner aucun lieu dans le périmètre consulté. Une erreur réseau, une limite atteinte ou une source indisponible empêche au contraire de conclure à partir de la recherche.
Pour ROOTE, contrôlez la réponse HTTP puis le statut métier, la collection attendue et la couverture. Cette démarche évite d’afficher « aucune toilette » lorsqu’un appel Services a échoué ou « aucun arrêt » après un délai d’attente dépassé.
Lire les trois niveaux d’une réponse
| Niveau | À contrôler | Conclusion possible |
|---|---|---|
| Transport | Connexion, délai et statut HTTP | La requête a-t-elle abouti ? |
| Contrat | JSON valide, version et champs attendus | La réponse est-elle exploitable ? |
| Résultat métier | status, collections, coverage, warnings et meta | Que sait-on dans le périmètre demandé ? |
Un code HTTP 200 ne suffit pas à valider une recherche. La réponse peut signaler une exécution partielle ou un statut error. À l’inverse, un 404 sur une route n’est pas un moyen normal d’exprimer une collection vide : vérifiez l’URL et le contrat.
Comprendre success, empty, partial et error
| Statut | Traitement recommandé |
|---|---|
| success | Afficher les entités après validation et conserver les limites |
| empty | Indiquer qu’aucun résultat n’a été retourné pour cette recherche |
| partial | Afficher les informations utilisables avec leurs avertissements |
| error | Présenter la recherche comme indisponible ; ne pas conclure à l’absence de lieux |
L’absence de résultat porte sur une requête et des sources connues. Elle ne prouve pas qu’aucun service n’existe physiquement. Une couverture non exhaustive, un filtre restrictif ou une limite appliquée peuvent réduire les résultats.
Un arbre de décision pour votre interface
1. La requête a-t-elle abouti ?
Non → indisponibilité réseau ou délai dépassé.
2. Le statut HTTP est-il acceptable selon le contrat ?
Non → traiter le code et le message d'erreur.
3. Le JSON respecte-t-il le schéma attendu ?
Non → réponse inexploitable, jamais "aucun résultat".
4. Le statut métier est-il error ?
Oui → recherche indisponible.
5. Le statut est-il partial ou la couverture limitée ?
Oui → résultats utilisables + avertissement.
6. La collection attendue est-elle vide ?
Oui → aucun résultat retourné dans ce périmètre.
Non → afficher les résultats et leurs limites.Vérifier les paramètres dans le bon ordre
Contrôlez d’abord latitude et longitude, leur ordre et la ville obtenue. Vérifiez ensuite l’unité du rayon et le vocabulaire des filtres. L’API Services utilise types=toilets ; une URL de carte utilise modes=toilets. Ces paramètres appartiennent à des contrats différents.
Élargissez ensuite une seule dimension à la fois : augmentez le rayon dans les limites de la route ou retirez un filtre pour un test explicite. Gardez la trace de la requête initiale. Si vous élargissez automatiquement, indiquez le nouveau périmètre à l’utilisateur.
Construire une recherche API autour de coordonnées GPS
Traiter une source indisponible sans perdre les autres
Une réponse partielle peut contenir des lieux issus de sources qui ont répondu alors qu’une autre a échoué. Conservez ces résultats, leurs attributions et l’avertissement pertinent. Ne présentez pas la liste comme exhaustive et ne remplacez pas des champs manquants par des valeurs par défaut trompeuses.
Une information ancienne conservée en cache peut aussi être utile si votre politique autorise ce repli. Elle doit rester identifiée comme ancienne. L’heure de réception de votre requête ne rajeunit pas l’observation d’origine.
Adapter les messages et les reprises
| Situation | Message à adapter à votre interface | Action |
|---|---|---|
| empty | Aucun résultat retourné dans cette zone avec ces filtres | Modifier la zone ou les filtres |
| partial | Certains résultats sont disponibles ; la recherche est incomplète | Afficher les résultats et l’avertissement |
| Erreur de validation | La recherche contient un paramètre invalide | Corriger la requête |
| Authentification ou droits | Cet accès ne permet pas cette recherche | Vérifier le compte ou le jeton |
| Limite ou indisponibilité | La recherche est temporairement indisponible | Respecter les consignes de reprise |
Pour un 429, consultez les consignes du service et l’éventuel Retry-After. Une erreur 400 demande une correction des arguments ; répéter la même requête ne la résout pas. Ne transformez pas un 401 en appel anonyme automatique si l’utilisateur a fourni un jeton.
Référence des erreurs API ROOTE
Tester les quatre états avant de publier
Préparez des réponses de test complètes, vides, partielles et en erreur, ainsi qu’un JSON invalide et un délai dépassé. Vérifiez le message affiché, les résultats conservés et le nombre de reprises. Le test essentiel est qu’une panne ne produise jamais une affirmation d’absence de services.
Appliquer ces règles à un assistant IA
Comprendre les formats de données de mobilité
Questions fréquentes
Une liste vide prouve-t-elle l’absence de toilettes ?
Non. Elle indique seulement qu’aucun résultat n’a été retourné pour cette recherche et les sources consultées.
Peut-on afficher une réponse partielle ?
Oui, si les entités utilisées sont valides et si vous conservez les avertissements et les limites nécessaires.
Faut-il relancer chaque erreur ?
Non. Corrigez les erreurs de paramètres ou d’accès ; bornez les reprises pour les incidents transitoires et respectez les consignes du service.