Erreurs, limites et nouvelles tentatives

API Les clients doivent prendre leurs décisions en fonction des codes d’état HTTP, des codes d’erreur stables et des en-têtes de réponse. Ne codifiez pas en dur les valeurs de quota par nom de forfait : les limites de la passerelle et du service dépendent du forfait actif, de la configuration de l’administrateur, du profil et de la politique produit en vigueur.

Enveloppe d’erreur

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "The API key does not have the required scope.",
    "status": 403
  }
}

Certains services proxy peuvent renvoyer une enveloppe spécifique au service. Conservez toujours le statut HTTP et le corps de la réponse dans des journaux de diagnostic structurés, mais masquez les identifiants et les données sensibles des utilisateurs.

Statuts courants

Statut	Signification	Action du client
400	Forme ou paramètre de requête non valide	Corrigez la requête ; ne la réessayez pas telle quelle.
401	Identifiants manquants, non valides, périmés ou révoqués	Remplacez ou renouvelez les informations d’authentification.
403	L’opération a été refusée en raison d’une politique relative à la portée, au service, au rôle, au forfait, au quota, à l’adresse IP ou à la ressource	Vérifiez le code d’erreur et la configuration actuelle du compte.
404	La route ou la ressource demandée est introuvable	Vérifiez la versionAPI, le chemin d’accès, l’identifiant et la visibilité de la ressource.
409	L’opération est en conflit avec l’état actuel de la ressource	Actualisez l’état avant de décider s’il convient de réessayer.
429	Une limite de requêtes par minute ou par jour a été atteinte	Attendez que Retry-After; réduisez la concurrence ou la fréquence d’interrogation.
500	La requête a atteint un service qui a échoué de manière inattendue	Ne réessayez que si l’opération peut être répétée en toute sécurité.
502, 503, 504	Une dépendance, un contrôle ou un service était temporairement indisponible	Appliquez un recul exponentiel borné avec gigue.

Les codes d’erreur de la passerelle peuvent inclure MISSING_API_KEY, INVALID_API_KEY, IP_NOT_ALLOWED, INSUFFICIENT_SCOPE, RATE_LIMIT_EXCEEDED, DAILY_LIMIT_EXCEEDED, RATE_LIMIT_UNAVAILABLE, NOT_FOUND, SERVICE_UNAVAILABLE, et INTERNAL_ERROR. Les services de destination peuvent renvoyer des codes supplémentaires pour leurs propres ressources et quotas.

En-têtes de limite en temps réel

Les requêtes authentifiées abouties et rejetées peuvent inclure :

X-RateLimit-Limit: <current minute limit>
X-RateLimit-Remaining: <requests left in the current minute window>
X-RateLimit-Reset: <Unix timestamp>
X-DailyLimit-Limit: <current daily limit>
X-DailyLimit-Remaining: <requests left in the current daily window>
Retry-After: <seconds>

Lisez ces valeurs lors de l’exécution. Les limites peuvent varier selon le forfait, le compte, le profil, la politique de l’administrateur et la phase de déploiement, et elles peuvent changer sans mise à jour du client.

Stratégie de réessai

Utilisez un recul exponentiel borné avec gigue pour les statuts transitoires. Une séquence pratique commence à environ une seconde et augmente jusqu’à un délai maximal modéré. Respectez une valeur supérieure Retry-After valeur lorsqu’elle est spécifiée.

Ne réessayez que lorsque l’opération ne présente aucun risque :

• GET Il est généralement sans risque de réessayer les requêtes.
• Une opération de création, d’envoi ou de mise à jour ayant échoué peut s’être achevée avant que la connexion n’ait échoué. Vérifiez l’état de la ressource avant de répéter l’opération.
• Ne pas réessayer 400, 401, ou la plupart des 403 réponses sans modifier la requête ni les informations d’identification.
• Définissez un nombre maximal de tentatives et affichez un message d’erreur utile une fois ce nombre atteint.

Réduisez le trafic inutile

• Mettez en cache les réponses d’autorisation en lecture seule ou de métadonnées pendant une courte période appropriée, plutôt que de les vérifier à chaque interaction avec l’interface utilisateur.
• Préférez webhooks pour connaître les événements pris en charge.
• Regroupez les requêtes identiques provenant d’une même charge de travail.
• Paginez les collections volumineuses et évitez toute concurrence illimitée.
• Utilisez le « CLIs » --json Générez la sortie dans des scripts plutôt que d’émettre desAPI requêtes en double à des fins de mise en forme.

Diagnostiquer un refus inattendu

1. Appel GET /v1/auth/whoami pour vérifier l’identité et la clé actives.
2. Appel GET /v1/auth/quota pour obtenir l’instantané actuel du quota de la passerelle.
3. Vérifiez que la clé dispose de la portée requise pour la route.
4. Vérifiez que le service de destination est activé pour le profil actif.
5. Vérifiez les autorisations liées aux rôles et à l’organisation dans le service de destination.
6. Enregistrez le statut, le code d’erreur, les en-têtes de réponse et l’heure de la requête avant de contacter CHAMPREP Assistance.