Codes d'erreur et diagnostic

Lors du diagnostic, commencez par noter : le code de statut HTTP, l'identifiant de requête renvoyé par la plateforme, l'ID du modèle, l'ID de la tâche, l'ID de la ressource et le code d'erreur d'origine.

N'enregistrez pas la clé API, le token de session de portrait ni l'adresse complète de téléchargement de la ressource ; masquez ces informations avant de les transmettre au support de la plateforme.

Signification des statuts HTTP

404 a trois causes possibles ; ne l'assimilez pas systématiquement à une « erreur d'ID »

C'est le point le plus fréquemment mal interprété lors du diagnostic :

Lorsque vous recevez un 404, vérifiez d'abord si le chemin et la méthode correspondent, avant de suspecter l'ID.

Une tâche vidéo introuvable renvoie 400, et non 404

Ce point est incohérent avec les autres interfaces et mérite une attention particulière :

La consultation d'une tâche vidéo renvoie 400 + une structure racine {code, message, data} ; ce n'est ni 404, ni la structure d'objet error décrite ci-dessous.

Il existe trois structures de réponse d'erreur

1. Interfaces de génération de modèle / image / vidéo —— objet error

En cas d'échec, l'interface renvoie un code HTTP non 2xx avec un objet error :

{
  "error": {
    "code": "invalid_parameter",
    "message": "请求参数不符合所选模型要求",
    "type": "invalid_request_error",
    "param": "size"
  }
}

code peut être une chaîne vide. Testé : en cas d'échec d'authentification et lorsque le JSON du corps de requête ne peut pas être analysé, code vaut "". Ne déterminez pas « s'il y a une erreur » en fonction du fait que code est vide ; basez-vous sur le code de statut HTTP et lisez message en priorité.

type n'est pas un champ de classification stable. Pour classifier, lisez code et ne vous fiez pas à la valeur de type.

2. Interfaces de la bibliothèque de ressources —— code racine

Renvoie un code HTTP non 2xx, où code correspond au statut HTTP :

{ "code": 404, "data": null, "msg": "素材不存在或无权访问" }

3. Consultation de tâche vidéo —— chaîne code racine

{ "code": "task_not_exist", "message": "task_not_exist", "data": null }

Notez qu'ici code est la chaîne task_not_exist, et non un nombre.

request id : l'identifiant clé pour le diagnostic

La plateforme écrit le request id directement dans error.message ; il n'est pas nécessaire de le chercher dans les en-têtes :

"message": "Invalid token (request id: 202609221135501066578648268d9d6uXuM5QgH)"

Extraction en une commande :

curl -s "$LOCOPAL_BASE_URL/v1/models" \
  -H "Authorization: Bearer sk-invalid" \
  | grep -oE 'request id: [A-Za-z0-9]+'

Joindre ce request id à votre ticket permet de réduire considérablement le temps de localisation.

Échec d'authentification

Lorsque la clé API est absente, incorrecte ou expirée, toutes les interfaces renvoient HTTP 401 et :

{
  "error": {
    "code": "",
    "message": "Invalid token (request id: ...)",
    "type": "new_api_error"
  }
}

Notez que code est une chaîne vide : c'est précisément pourquoi il est rappelé ci-dessus de « ne pas se fier à code ».

Erreurs de modèles et de génération

Erreurs de la bibliothèque de ressources

Une revue de ressource non terminée n'est pas une erreur : la requête renvoie 200 avec status à Processing ; continuez simplement à interroger le même ID de ressource.

Une sortie vide d'un modèle de raisonnement n'est pas non plus une erreur HTTP : si la réponse est 200, que finish_reason vaut length et que usage.completion_tokens_details.reasoning_tokens a atteint la limite de sortie, augmentez le quota de sortie ou utilisez un modèle non raisonneur.

Erreurs d'autorisation de portrait

Limitation de débit et nouvelles tentatives

• 429 indique des requêtes trop fréquentes ; réessayez après un backoff comme indiqué, sans nouvelles tentatives concurrentes ;
• pour le statut des ressources, interrogez toutes les 5 à 10 secondes ; pour les tâches vidéo, toutes les 5 à 15 secondes ;
• ne réessayez que pour 429 et les 5xx passagers ; pour 400 / 401 / 403 / 404, corrigez directement la requête ;
• avant de réessayer, interrogez d'abord par ID de tâche / ID de ressource pour éviter les créations et facturations en double.

Vérification rapide

1. Authorization est-il bien Bearer <API Key>, et la clé est-elle toujours activée ;
2. le domaine de la requête est-il bien l'adresse actuellement indiquée par la console (par défaut https://locopalai.com ; pour les modèles internationaux, il peut s'agir de https://us-api.locopalai.com) ;
3. model provient-il bien de data[].id retourné par /v1/models ;
4. le status de la ressource est-il déjà Active ;
5. l'adresse de l'image / vidéo de référence est-elle une adresse http(s) directement accessible depuis l'internet public, sans dépendre de Cookie ni de Referer ;
6. la même tâche / ressource a-t-elle déjà été soumise en double.

Éléments à joindre lors du contact avec le support

• l'heure de la requête et le chemin de l'interface ;
• le code de statut HTTP et le corps de réponse complet (clé API masquée) ;
• l'identifiant de requête, l'ID de tâche ou l'ID de ressource renvoyé par la plateforme ;
• l'ID de modèle et les paramètres concernés ;
• un exemple de requête minimal reproductible.