Structure de réponse et codes d'erreur de l'Open API HappyOyster, y compris les codes métier, les scénarios typiques et les suggestions de gestion.
Ce document décrit la structure de réponse et les codes d'erreur de l'Open API HappyOyster. Il s'applique à tous les points de terminaison Open API des modèles Adventure, Directing et Acting.
Structure de réponse
Une fois qu'une requête passe l'authentification de la passerelle (tant pour les succès métier que pour les erreurs métier), la réponse renvoie toujours HTTP 200 avec la structure JSON suivante comme corps :
{
"code": 0,
"message": null,
"data": {}
}
| Champ | Type | Description |
|---|---|---|
code | integer | Code de retour métier. 0 signifie succès ; une valeur non-0 signifie une erreur métier — voir la liste des codes d'erreur ci-dessous. |
message | string | null | Message d'erreur lisible par l'homme. null lorsque code=0. |
data | object | null | Charge utile métier. En cas de succès, contient l'objet de réponse spécifique au point de terminaison ; en cas d'erreur, généralement null. |
Les échecs au niveau de la passerelle, tels que la vérification de l'AK, de la signature ou de l'horodatage, sont rejetés directement ; ces réponses ne suivent donc pas cette structure et sont généralement renvoyées avec un code d'état HTTP 4xx / 5xx — voir Code d'erreur.
Liste des codes d'erreur
| code | Description | Scénarios typiques et gestion |
|---|---|---|
0 | Succès | Requête réussie ; lire data. |
400000 | Paramètres de requête invalides | mode ne correspond pas au modèle actuel ; prompt ou firstFrameImage est manquant ; prompt est trop long ; creationModel / uploadMode / resolution / aspectRatio / perspective a une valeur illégale ; le format de l'image ou de l'ID chiffré est invalide. Corriger les paramètres conformément à la documentation de l'API et réessayer. |
400001 | Échec de la récupération ou du stockage de l'URL de l'image | L'URL de l'image de première trame ou de référence est inaccessible ou expirée. Vérifiez l'accessibilité et la validité de l'URL, puis réessayez de créer le Monde. |
401010 | ticket invalide ou expiré | Enter travel (enter-travel). Appeler get-travel-credential à nouveau pour obtenir un nouveau ticket. |
401011 | ticket déjà utilisé | Enter travel. Le ticket est à usage unique ; en obtenir un nouveau. |
403001 | Le Monde n'existe pas, a été supprimé, ne vous appartient pas ou n'appartient pas au modèle actuel | Requête, échange d'identifiants, entrée dans le Travel et filtrage de liste. Lors de la suppression, ce code est retourné uniquement pour les ID inter-comptes, inter-espaces de travail ou inter-modèles ; un ID déjà inexistant sous le même compte retourne code=0, deleted=false. |
403002 | Le World n'est pas ready ou indisponible | Échange d'identifiants, enter travel. Interroger l'état de la construction jusqu'à ce qu'elle soit ready avant d'opérer. |
403003 | Ce point de terminaison autorise uniquement la API Key principale | Gestion des Worlds, liste des Travels, artefacts, etc. Appeler avec la clé API principale (commence par sk-). |
403004 | Le contenu d'entrée a échoué à la politique de sécurité du contenu | Créer un World, envoyer instruct. Ajuster le contenu textuel et réessayer. |
403005 | L'image d'entrée a échoué à la vérification des droits d'auteur ou de la propriété intellectuelle | Créer un World. Remplacer par une image conforme et réessayer. |
403007 | Fonctionnalité ou quota de service non activé | Création, échange d'identifiants, enter travel. Confirm que la capacité du modèle correspondante est activée. |
403008 | Configuration de capacité temporairement indisponible | Création, échange d'identifiants, entrée dans le Travel. Réessayez plus tard ou contactez le fournisseur de services pour augmenter la capacité. |
404000 | Le Travel n'existe pas, ne vous appartient pas, n'appartient pas au modèle actuel ou ne possède aucun artefact disponible | Interrogation du statut du Travel, contrôle, fin, interrogation des artefacts. |
409000 | La requête est en conflit avec l'état actuel de la ressource | Points de terminaison de contrôle tels que pause, reprise, fin et instruct ; également renvoyé lors de l'appel d'un point de terminaison non pris en charge par un modèle. |
429001 | La concurrence pour la spécification actuelle est saturée | Entrée dans le Travel. Réessayez plus tard ou augmentez la spécification de concurrence. |
429002 | Capacité disponible insuffisante | Enter travel. Réessayer ultérieurement. |
500000 | Erreur système interne | Exceptions non classées ; peuvent également être renvoyées lors de l'appel d'un point de terminaison non pris en charge (par exemple, rewind sur certains modèles). |
500001 | Échec de l'allocation des ressources de streaming | Enter travel. Réessayer ultérieurement. |
L'accès inter-modèles ne révèle pas si la ressource existe : les points de terminaison World renvoient code=403001 et les points de terminaison Travel renvoient code=404000.
errorCode d'échec de Travel
Lors de l'interrogation du statut du Travel ou de la liste des Travels, les éléments avec status=failed comportent en outre le champ structuré errorCode et une description en anglais errorMessage (voir la documentation de l'API correspondante pour la structure de réponse d'échec). Le texte errorMessage pour le même errorCode peut différer entre les points de terminaison d'interrogation et la réponse End Travel ; effectuer la bifurcation sur errorCode, et non sur errorMessage.
| errorCode | errorMessage | Description |
|---|---|---|
TRAVEL_SESSION_INIT_FAILED | Failed to allocate inference resources. | La session d'inférence n'a pas pu s'initialiser lors de l'entrée dans le travel, généralement en raison de ressources d'inférence insuffisantes |
TRAVEL_NO_STREAM_AUTO_END | No video stream was received before timeout. | Le client n'a pas reçu le flux avant le délai d'attente ; terminer le Travel en passant failCode dans la requête End Travel |
TRAVEL_STREAM_CREATE_FAILED | Failed to create the video stream. | Échec de la création du canal de streaming |
CONTENT_VIDEO_MODERATION_REJECTED | Something went wrong. | L'image de l'expérience a été interrompue par la politique de sécurité du contenu |
TRAVEL_RUNTIME_FAILED | The experience was interrupted by a runtime error. | Autres échecs d'exécution, ou le serveur n'a pas enregistré de raison spécifique |
Tout errorCode non répertorié peut être considéré comme une défaillance inconnue.