Branche sur des codes stables, pas sur des messages humains

Les réponses à l’erreur utilisent application/problème+json avec un statut HTTP et un code lisible par machine. Mapper les codes dans votre propre modèle d’erreur typé à la frontière d’accès aux données. Les détails lisibles par l’humain sont des diagnostics sûrs et peuvent être localisés ou clarifiés ultérieurement ; elles ne doivent jamais piloter le flux de contrôle des applications ni être affichées comme des exceptions brutes de l’infrastructure.

Considérez le 401 comme une configuration ou une révocation

Une réponse authentication_required signifie que X-API-Key est absent, malformé ou révoqué. Réessayer automatiquement avec la même clé ne corrigera pas le problème et risque d’amplifier le bruit. Arrêtez l’opération, alertez le propriétaire de l’intégration et vérifiez le déploiement du secret. N’utilisez jamais la clé d’un autre client et n’exposez pas la réponse brute à un navigateur.

HTTP 402 est une limite budgétaire

insufficient_credits est déterministe et inclut le coût et le solde restant. Suspendre les tâches planifiées, préserver l’interface interactive en lecture seule des données mises en cache lorsque cela est approprié et envoyer le propriétaire de la facturation vers le tableau de bord développeur. Une boucle de retentative serrée ne crée que des appels rejetés répétés et masque l’action commerciale requise.

Nouvelle tentative uniquement pour des opérations limitées, sûres

Respectez Retry-After pour les réponses 429 et utilisez un backoff exponentiel avec jitter lors des erreurs fournisseur 502 transitoires. Les requêtes GET et le provisionnement idempotent des utilisateurs se prêtent naturellement aux nouvelles tentatives. Ne répétez pas aveuglément une modification de connexion après une réponse indéterminée : listez d’abord les comptes et vérifiez si la ressource a été créée.

Transportez des identifiants de corrélation à travers votre limite

Envoyez un X-Correlation-ID validé et incluez-le dans des journaux structurés avec portfolioId, l’opération et la latence. Cela rapproche les diagnostics sans enregistrer de secrets. Fournissez une référence sûre plutôt que les charges du fournisseur, les détails de base de données ou les traces.