Erreurs et dépannage
Identifiez les problèmes d’appel selon l’origine de l’erreur et le statut HTTP, puis choisissez une récupération sûre.
En cas d’échec, conservez le statut HTTP et l’erreur expurgée, puis déterminez si le problème vient de la requête, de l’authentification, du modèle ou du serveur. Ne répétez pas continuellement la même requête sans identifier la cause.
Protéger d’abord les identifiants et les données client
Les diagnostics ne doivent pas contenir de clé API complète, de Header Authorization ou x-api-key, de Cookie, de mot de passe, de prompt complet, de fichiers client ni d’autres informations sensibles.
Identifier d’abord l’origine de l’erreur
| Origine | Symptômes courants | Action recommandée |
|---|---|---|
| Contenu de la requête | JSON invalide, champs absents, types incorrects ou format de fichier inadapté | Corriger la requête selon l’erreur, sans la renvoyer à l’identique |
| Authentification et droits | Clé absente, invalide ou sans accès au modèle cible | Vérifier la Base URL, les Headers du protocole, l’état de la clé et les droits sur le modèle |
| Modèle et ressources | Identifiant du modèle, de tâche ou chemin inexistant | Recopier l’identifiant du catalogue et vérifier le compte propriétaire |
| Plateforme ou service amont | Indisponibilité temporaire, délai dépassé ou erreur amont | Conserver le diagnostic et limiter les tentatives ; arrêter si l’échec persiste |
| Tâche asynchrone | Échec après soumission, traitement prolongé ou résultat indisponible | Consulter d’abord la tâche d’origine pour éviter les doublons |
Un échec peut fournir plusieurs indices. Un 404 peut indiquer un endpoint incorrect ou un modèle ou une tâche inexistants ; examinez l’URL finale et le corps de l’erreur.
Aide-mémoire des statuts HTTP
| Statut HTTP | Signification courante | Récupération recommandée |
|---|---|---|
400 | Format, paramètres ou entrée incorrects | Corriger la requête avant de la renvoyer |
401 | Clé absente ou invalide, ou Header d’authentification incorrect | Vérifier l’authentification du protocole et remplacer la clé si nécessaire |
403 | Droits du compte, de la clé ou du modèle insuffisants | Vérifier l’état du compte, les limites du jeton et les droits sur le modèle |
404 | Base URL, endpoint, modèle ou tâche inexistants | Vérifier l’URL finale, les identifiants et le compte propriétaire |
429 | Limite de fréquence, de concurrence, de quota ou de capacité | Arrêter les appels fréquents, réduire la charge selon l’erreur et réessayer plus tard |
500–599 | Plateforme, passerelle ou service amont temporairement incapable de traiter la requête | Conserver le diagnostic et limiter les tentatives avec backoff |
Ces statuts orientent le diagnostic. Les codes applicatifs varient selon le protocole et le service amont ; combinez le statut HTTP, le corps réel de l’erreur et la référence API.
Procédure de diagnostic recommandée
Consigner l’échec
Conservez l’heure et le fuseau horaire, la Method, le Path, le modèle, le statut HTTP et un message d’erreur expurgé de longueur limitée. Ajoutez le Request ID s’il est fourni.
Vérifier l’adresse et l’authentification
Utilisez https://api.agtcloud.cn/v1 comme Base URL et vérifiez l’absence de /v1/v1 dans l’URL finale. Les API compatibles OpenAI utilisent généralement Authorization: Bearer your-api-key ; pour les autres protocoles, vérifiez les Headers de la référence.
Vérifier le modèle et le contenu
Vérifiez que l’identifiant provient de la liste visible pour le compte, puis contrôlez le Content-Type, le JSON, les champs requis, les fichiers et la taille d’entrée.
Déterminer si une nouvelle tentative est appropriée
Corrigez d’abord les 400, 401, 403 et les ressources clairement inexistantes. Les pannes réseau temporaires ou 5xx peuvent faire l’objet de tentatives limitées avec des délais croissants.
Préparer des informations expurgées
Si le problème persiste, préparez une reproduction minimale et un diagnostic. Ne copiez pas de clé complète, de prompt client, de fichier ni de réponse non expurgée.
Gérer les nouvelles tentatives en sécurité
- Pour une lecture classique confrontée à une panne temporaire, limitez les tentatives avec backoff.
- Corrigez les paramètres, l’authentification et les droits avant de renvoyer la requête.
- Avant de répéter une création, un appel externe ou toute requête avec effets de bord, vérifiez si l’original a déjà pris effet.
- Pour une tâche asynchrone, consultez d’abord l’identifiant d’origine ; un délai dépassé côté client ne justifie pas un doublon.
- Limitez le nombre de tentatives et l’attente totale ; si l’échec persiste, arrêtez les appels automatiques et conservez le diagnostic.
Informations à préparer
| Information | Exemple ou description |
|---|---|
| Heure de l’incident | Date, heure et fuseau horaire |
| Requête | Method et Path, sans clé API complète |
| Cible | Identifiant du modèle et, pour une tâche asynchrone, de la tâche |
| Résultat | Statut HTTP et erreur expurgée |
| Caractéristiques | Streaming, présence d’outils et caractère asynchrone |
| Environnement client | Nom et version du SDK, runtime et reproduction minimale |
| Suivi | Conserver le Request ID s’il est fourni |
Consultez la Référence des codes d’erreur pour les codes applicatifs et leurs traitements. Si nécessaire, consultez Request ID et la FAQ. Pour un premier appel, revérifiez le Démarrage rapide et la Clé API, Base URL et authentification.