Un écran de recherche ne se limite pas à des résultats ou une erreur

Un scénario d’interface, pas un indicateur de santé

Voici des états proposés pour une application de randonnée que vous développez. Ce ne sont ni des réponses capturées, ni une démonstration fonctionnelle, ni la preuve que des données sur offline maps sont disponibles. Le randonneur utilise votre application ; l’opérateur du compte API gère la clé et les crédits. Donnez à chacun les informations sur lesquelles il peut agir.

Avant la première recherche, expliquez que la fonction consulte des discussions historiques. Une suggestion comme offline maps peut aider à commencer, mais n’affichez pas de recommandations inventées comme si une recherche avait déjà abouti. Conservez une action Rechercher explicite pour que la saisie et l’exploration du formulaire ne déclenchent pas nécessairement une requête payante.

Chargement : garder la question visible

Pendant l’attente, conservez la question envoyée et les filtres sélectionnés. Signalez le chargement dans la zone des résultats, évitez les envois multiples de cette action et accompagnez toute animation d’un libellé accessible. Un délai ne suffit pas à identifier une panne du service ou sa cause.

Si la personne modifie la question avant l’arrivée d’une réponse précédente, associez chaque réponse à sa saisie initiale. Ne placez pas silencieusement les résultats de l’ancienne question sous la nouvelle. Ce comportement relève de votre implémentation à tester, pas d’une garantie de tri ou d’annulation de l’API.

Une réussite peut contenir des données ou être vide

Lorsque des enregistrements arrivent, affichez uniquement les champs disponibles et identifiez le contenu comme historique. Un commentaire n’a pas forcément de titre ; une date absente doit rester inconnue. Décrivez la page visible plutôt que d’annoncer un total exact si pagination.relation vaut gte ou unknown.

Une réponse vide réussie constitue un résultat distinct. Un message possible est : Cette requête n’a renvoyé aucun enregistrement. Proposez une modification volontaire des termes ou des filtres tout en conservant la saisie. N’affirmez pas que la discussion n’existe nulle part. Une récupération vide réussie coûte tout de même un crédit.

400, 401 et 402 concernent des responsables différents

HTTP 400 indique une entrée invalide. Examinez le paramètre concerné : paramètre non pris en charge, page hors limites ou date ne respectant pas YYYY-MM-DD, par exemple. Expliquez au lecteur le champ qu’il peut corriger lorsque c’est pertinent ; conservez les erreurs de contrat du serveur dans les diagnostics de l’opérateur.

HTTP 401 signifie que la clé API du service est absente ou invalide. Cela ne prouve pas que la session du lecteur a expiré, et ces clés n’ont pas de mécanisme documenté d’expiration programmée. L’opérateur vérifie la clé du domaine et toute régénération récente. Ne demandez pas au randonneur de fournir une clé ou de se connecter au compte du service.

HTTP 402 signifie que le compte du service manque de crédits. Un message destiné au lecteur pourrait indiquer que la recherche de discussions est momentanément suspendue. L’opérateur peut ouvrir Clé et crédits pour vérifier le solde. Une nouvelle requête est une action séparée après résolution de la cause ; répéter simplement l’ancienne n’est pas une solution.

429, défaillance en amont et livraison incertaine

HTTP 429 signifie qu’une limite de requêtes a été atteinte. Respectez Retry-After, réduisez les envois répétés et permettez un nouvel essai au moment opportun. La limite peut concerner un serveur ou compte partagé ; évitez de blâmer un seul lecteur. Ne lancez pas de boucle automatique sans limite.

Le gateway signale les défaillances de la source par HTTP 502. Conservez la question et proposez explicitement de réessayer, sans promettre la réussite suivante. Le crédit réservé est restitué si la requête en amont échoue ; la réponse peut aussi signaler une régularisation en attente. Si votre application perd toute la réponse, la facturation finale est incertaine : le serveur a pu terminer avec succès.

La route publique /v1/status fournit une déclaration statique du périmètre et montre que son gestionnaire HTTP répond. Elle ne teste pas les recherches et ne certifie pas l’état de la source. Basez les décisions opérationnelles sur le résultat réel. Retournez au Parcours de l’application pour le scénario complet ou à la note sur les états pour les choix d’implémentation.