Gestion des erreurs
Relancer la création d’une génération
Pour POST /v2/generate, envoyez une Idempotency-Key dès la première tentative et réutilisez-la avec le même payload à chaque relance. Le guide couvre les réponses rejouées, les conflits de payload, la rétention et toutes les erreurs IDEMPOTENCY_*. Une réponse perdue ou IDEMPOTENCY_OUTCOME_UNKNOWN n’autorise ni une nouvelle clé ni une relance sans clé. Une réponse au résultat inconnu peut inclure generationId ; interrogez-le quand il est disponible.
Sans clé, un timeout ou un échec de transport lors de la création peut laisser l’acceptation incertaine. Confirmez le résultat avant de soumettre à nouveau. Les conseils généraux sur les délais entre les tentatives ci-dessous ne rendent pas sûre la répétition d’une création sans clé.
Codes de statut HTTP
En appelant l’API sync. labs, vous pouvez rencontrer les codes de statut HTTP suivants. Ils sont renvoyés au niveau HTTP, avant tout code d’erreur propre à une génération.
HTML 403 ou Cloudflare Access denied
Si une requête vers api.sync.so renvoie une page HTML mentionnant Cloudflare avec un HTTP 403, Access denied ou l’erreur 1010, traitez-la séparément des erreurs JSON de l’API ci-dessous. Un blocage Cloudflare peut survenir avant la validation de l’API : à lui seul, il n’établit donc pas que votre clé API, votre forfait ou vos médias sont invalides.
Arrêtez les relances répétées et contactez support@sync.so en indiquant la méthode et le point de terminaison de la requête, l’horodatage UTC, le Ray ID Cloudflare, la version du client/SDK et une réponse ou capture d’écran expurgée. Pour les uploads, incluez le type de contenu et la taille des fichiers. N’envoyez pas de clés API, de en-têtes d’autorisation ni d’URL de médias signées. Le support a besoin de la réponse précise pour enquêter ; ne supposez pas que tous les 403 ont la même cause.
Un 403 renvoyé par une URL d’upload de stockage présignée est un cas différent : consultez le guide de dépannage Asset Uploads pour les vérifications de type de contenu et d’expiration d’URL.
Codes d’erreur lisibles par machine
Chaque génération en échec contient un errorCode stable et lisible par machine, en plus du message error lisible par un humain. L’errorCode apparaît à la fois dans la réponse de Get Generation (GET /v2/generate/{id}) et dans le corps du webhook envoyé à la fin d’une tâche.
Basez votre gestion des erreurs sur errorCode, pas sur la chaîne error. Le message error est destiné aux humains et peut être reformulé avec le temps ; errorCode est un identifiant stable que vous pouvez utiliser sans risque dans un switch de votre code.
Une génération en échec se présente ainsi :
Les réponses d’erreur des points de terminaison de requête (assets, voices, TTS et rejets de generate à la soumission) ont la même forme lisible par machine, avec deux champs optionnels en plus : field nomme le champ de la requête à l’origine de l’échec (par exemple voiceId ou input[].assetId), et docsUrl pointe vers la page de documentation concernée. Les erreurs 500 non gérées incluent un requestId à transmettre au support, avec errorCode: internal_error :
Rechercher un code dans le catalogue d’erreurs
GET /v2/errors renvoie le catalogue complet des codes d’erreur, codes de génération et codes de requête API ci-dessous, sous forme de tableau d’objets { code, message, suggestion }. Le point de terminaison est non authentifié : aucun en-tête x-api-key n’est requis, vous pouvez donc obtenir, à l’exécution, la signification de chaque errorCode et une suggestion de correction.
Une entrée typique se présente ainsi :
Lire et résoudre un code d’erreur
Quand une génération échoue, lisez son errorCode et recherchez-le dans le catalogue renvoyé par GET /v2/errors.
Erreurs de validation lors de la soumission
Certaines requêtes sont rejetées lors de la soumission : l’API répond par une erreur sur la requête elle-même, avant tout rendu, au lieu d’accepter la tâche et de la faire échouer plus tard. Ces rejets renvoient un statut HTTP et un errorCode lisible par machine dans le corps de la réponse, pour que vous puissiez corriger la requête et la soumettre à nouveau sans gaspiller de génération.
Une erreur à la soumission renvoie errorCode dans la réponse HTTP. Les échecs de validation peuvent survenir avant la création de la génération, mais une soumission incertaine peut déjà avoir une génération. Interrogez generationId quand il est fourni et suivez les recommandations de récupération idempotente avant de relancer.
Les erreurs de limite de débit et de dépendance (429/503/504) reprennent aussi leurs consignes de relance dans des en-têtes : Retry-After (en secondes) et, pour les 429 de concurrence, X-Sync-Concurrency-Limit et X-Sync-Active-Generations.
Codes d’erreur des requêtes API
Au-delà des échecs de génération, les points de terminaison assets, voices, TTS et de téléchargement de génération renvoient leurs propres valeurs errorCode stables dans les réponses d’erreur. Le cas échéant, le corps de la réponse contient aussi field (le champ de requête en cause) et docsUrl (un lien vers la page de documentation concernée). Tous ces codes figurent dans le catalogue d’erreurs (GET /v2/errors).
Assets
Voix et TTS
Téléchargements
GET /v2/generations/{id}/download renvoie une URL pour télécharger la sortie d’une génération terminée. Les générations manquantes, supprimées ou d’une autre organisation renvoient generation_not_found (404), comme décrit plus haut. Une clé API manquante, invalide ou révoquée renvoie 401, et un id qui n’est pas un UUID renvoie 400. Les codes propres au téléchargement sont :
Capacité d’upload batch
Un upload batch multipart peut renvoyer 503 avec errorCode: upload_capacity_unavailable. Aucun batch n’a été créé. Relancez la même requête après le nombre de secondes indiqué dans Retry-After. Vous pouvez aussi envoyer les enregistrements dans un corps JSON rows.
Découpes audio
POST /v2/audio-trims et GET /v2/audio-trims/{id} préparent un asset audio plus court pour une vidéo partielle. Ces codes ne figurent pas dans le catalogue d’erreurs.
Une découpe qui ne parvient pas à décoder ou couper l’audio se termine avec status: failed et errorCode: audio_trim_failed sur GET /v2/audio-trims/{id}. Vérifiez que la source est un fichier audio lisible, puis lancez une nouvelle découpe avec une nouvelle Idempotency-Key.
Réutiliser une Idempotency-Key avec un corps différent renvoie 409. Une Idempotency-Key manquante, ou qui ne fait pas 1 à 128 caractères parmi [A-Za-z0-9._~-], renvoie 400. Une source audio ou une découpe qui n’existe pas ou à laquelle vous n’avez pas accès renvoie 404. Envoyez d’abord les sources externes et découpez-les par assetId.
Générations rejetées et en échec
REJECTED et FAILED sont des statuts finaux. Inspectez errorCode et error dans la réponse de génération ou le webhook. REJECTED signifie que la requête ou le compte doit être corrigé avant une nouvelle tentative. FAILED signifie que le traitement s’est arrêté à cause d’une erreur opérationnelle. Suivez la procédure de récupération du code renvoyé, et contactez le support si le problème persiste.
NO_OP est aussi un statut final : la génération s’est terminée, mais aucune image n’a été synchronisée, la sortie est donc la vidéo d’entrée inchangée. Elle porte l’un des codes de lip sync omis. Consultez Génération terminée sans synchronisation labiale.
Une requête refusée avant l’existence d’une génération renvoie son erreur dans la réponse HTTP. Arrêtez d’interroger une génération dès qu’elle atteint un statut final (COMPLETED, NO_OP, FAILED ou REJECTED). Pour les relances, suivez Idempotent requests.
Que signifient les codes d’erreur de l’API ?
Les codes ci-dessous sont regroupés par catégorie, les plus fréquents d’abord.
Erreurs de validation des entrées
generation_unsupported_model
Message : “The requested model is not supported for this operation.”
Description : Cette erreur est renvoyée quand vous essayez d’utiliser un modèle qui n’est pas compatible avec l’opération ou le point de terminaison API actuel.
Résolution :
- Consultez la documentation des modèles pour voir quels modèles sont pris en charge pour cet appel API précis.
- Modifiez votre requête pour utiliser un modèle pris en charge.
- Si vous pensez qu’il s’agit d’une erreur, contactez notre équipe support en détaillant votre cas d’usage.
generation_plan_duration_exceeded et generation_model_duration_exceeded
Message : “The input exceeds your plan’s output-duration limit.” ou “The input exceeds the selected model’s duration limit.”
Description : Il n’y a pas de limite fixe de durée audio pour le lip sync. La sortie la plus longue que vous pouvez générer dépend de votre forfait (consultez Facturation), et certains modèles ont leur propre plafond, comme 15 secondes pour react-1. Un rejet à la soumission renvoie 402 generation_plan_duration_exceeded, décrit dans Erreurs de validation lors de la soumission.
Résolution :
- Coupez ou découpez le média pour que la sortie respecte la limite.
- Pour une limite de modèle, choisissez un modèle avec une limite plus élevée (consultez List Models).
- Pour une limite de plan, passez à un forfait supérieur pour des générations plus longues.
Les scripts de synthèse vocale sont validés à la soumission : script accepte de 1 à 5 000 caractères. Consultez Text-to-Speech.
generation_input_validation_failed
Message : “Something in your input is invalid. Please check your media and settings, then try again.”
Description : Cette erreur survient quand les données d’entrée fournies ne respectent pas les critères de validation requis pour le traitement. Causes fréquentes : une URL d’entrée ou un assetId qui ne mène pas à un média récupérable, ou un média dans un format non pris en charge.
Résolution :
- Vérifiez que vos données d’entrée respectent toutes les exigences et spécifications de l’API.
- Vérifiez que tous les champs requis sont présents et correctement formatés.
- Vérifiez que les formats de fichier, les tailles et les autres paramètres sont dans les limites acceptées.
- Si le problème persiste, contactez notre équipe support avec des détails sur vos données d’entrée pour obtenir de l’aide.
generation_input_audio_invalid
Message : “We could not read the audio file metadata. Please try a different audio file.”
Description : Cette erreur survient quand les métadonnées du fichier audio sont manquantes ou illisibles. Le code équivalent pour la vidéo est generation_input_video_invalid, que vous pouvez corriger de la même façon en réencodant en MP4 H.264. Causes typiques : fichiers audio corrompus, en-têtes endommagés, ou fichiers issus d’outils qui produisent des métadonnées non standard.
Résolution :
- Réencodez votre fichier audio avec un outil standard comme FFmpeg pour garantir des métadonnées correctement formatées :
- Vérifiez que votre fichier audio s’ouvre et se lit correctement dans un lecteur multimédia.
- Vérifiez que le fichier audio n’a pas été corrompu pendant le téléchargement ou le transfert.
- Si le problème persiste, essayez de convertir votre audio dans un autre format pris en charge (WAV, MP3, OGG, FLAC) et soumettez-le à nouveau.
generation_input_face_selection_invalid
Message : “We could not use the selected speaker face for this video. Please select the face again or try auto-detect.”
Description : Cette erreur survient quand le visage du locuteur sélectionné manuellement ne peut pas être utilisé pour la génération. Le visage sélectionné n’est peut-être pas détecté dans la vidéo, les coordonnées fournies peuvent se trouver hors du cadre de la vidéo, ou la sélection du locuteur actif peut être invalide.
Résolution :
- Relancez la détection de visage et sélectionnez à nouveau le locuteur, en vous assurant que le visage est bien visible dans l’image choisie.
- Vérifiez que les coordonnées ou bounding boxes fournies manuellement se trouvent dans les dimensions de la vidéo.
- Vous pouvez aussi désactiver la sélection manuelle du locuteur pour laisser le système détecter automatiquement le locuteur actif, puis soumettre à nouveau.
Erreurs de la Batch API
Les erreurs de validation batch sont des réponses 400 qui contiennent uniquement un message ; elles n’ont pas d’errorCode. Les refus liés à l’accès, au plan et à la capacité utilisent les codes ci-dessous. Les dry runs nécessitent la même approbation de l’organisation et le même plan que la création de batch.
L’accès batch n’est pas activé (batch_access_not_enabled)
Statut : 403
Description : Votre organisation n’a pas été approuvée pour créer des batches. L’accès est désactivé par défaut, y compris pour les nouveaux abonnements Scale. Les dry runs nécessitent la même approbation. Les batches existants continuent d’être traités et restent consultables quand l’accès à la création est retiré.
Résolution : Contactez support@sync.so pour demander l’accès pour votre organisation. Passer à un forfait supérieur n’active pas l’accès automatiquement.
Le batch nécessite le plan Scale (plan_feature_unavailable)
Statut : 402
Description : La Batch API nécessite l’approbation de l’organisation et un forfait Scale ou supérieur (Scale, Enterprise, forfaits partenaires et programmes). Les autres forfaits et les comptes gratuits ne peuvent pas créer de batches. Le corps de la réponse contient requiredPlan et une billingUrl : requiredPlan vaut scale, ou enterprise sur les plans à crédits, car aucun forfait à crédits en libre-service n’inclut le batch.
Résolution :
- Passez au plan Scale, ou contactez l’équipe commerciale au sujet d’Enterprise, et demandez l’approbation de votre organisation pour utiliser la Batch API.
- Pour exécuter quelques générations à la fois sans batch, envoyez des requêtes
POST /v2/generateen parallèle dans la limite de votre concurrence. Consultez When to use batch, and when not to.
Limite de concurrence batch (concurrency_limit_reached)
Statut : 429, avec les en-têtes Retry-After et X-Sync-Concurrency-Limit
Message : “Batch concurrency limit reached. You have X active batches and your plan allows Y. Please wait for existing batches to complete or upgrade your plan for higher limits.”
Description : Vous exécutez déjà autant de batches que votre forfait l’autorise. Chaque batch actif occupe un emplacement d’une limite de batches égale à la limite de concurrence de votre forfait. Le corps de la réponse contient activeBatches, concurrencyLimit et retryAfterSeconds.
Résolution :
- Attendez
retryAfterSeconds, ou la fin d’un batch actif. - Vérifiez vos batches actifs avec
GET /v2/batch.
Messages de validation batch
Les numéros de ligne comptent les enregistrements non vides ; avec un corps JSON rows, la ligne N correspond à rows[N-1].
Refus de lignes d’édition de dialogue
Exemple : {"statusCode": 422, "errorCode": "dialogue_edit_not_found", "lineNumber": 3, "message": "Record at line 3: The dialogue edit was not found in this organization."}
Description : Les lignes de batch qui contiennent dialogueEdit (accès anticipé) sont vérifiées à la soumission, y compris avec dry_run. Si une ligne ne peut pas être rendue, aucun batch n’est créé. La réponse contient le même errorCode que celui renvoyé par POST /v2/generate pour cet aperçu, comme dialogue_edit_not_found, dialogue_edit_not_completed, dialogue_edit_source_mismatch ou dialogue_edit_batch_mixed_sources, ainsi que le lineNumber de la première ligne en échec. Les numéros de ligne comptent les enregistrements non vides ; avec un corps JSON rows, la ligne N correspond à rows[N-1]. Les autres erreurs d’enregistrement batch, comme un JSON invalide, indiquent la ligne uniquement dans message.
Résolution :
- Trouvez la ligne à
lineNumberet corrigez-la comme décrit dans Dialogue edit refusals. - Validez à nouveau avec
dry_runjusqu’à ce que la réponse soit{"status": "VALIDATED"}.
Lip sync omis
Ces codes accompagnent le statut NO_OP. La génération s’est terminée et son outputUrl est la vidéo d’entrée inchangée, avec la parole générée ou l’audio doublé le cas échéant. Le lip sync n’est pas facturé. Consultez Génération terminée sans synchronisation labiale.
generation_lipsync_skipped_no_face
Message : “No face was detected in the video, so nothing was lip-synced.”
Résolution : Utilisez une vidéo où le visage du locuteur est bien visible et suffisamment grand dans le cadre, puis soumettez à nouveau.
generation_lipsync_skipped_speaker_not_found
Message : “No face was found at the selected speaker position, so nothing was lip-synced.”
Résolution : Sélectionnez un point sur le visage du locuteur dans une image où il est visible, ou utilisez la détection automatique du locuteur, puis soumettez à nouveau.
generation_lipsync_skipped_no_active_speaker
Message : “Automatic speaker detection found no one speaking, so nothing was lip-synced.”
Résolution : Sélectionnez vous-même le locuteur avec un numéro d’image et des coordonnées, puis soumettez à nouveau. Consultez Sélection du locuteur.
generation_lipsync_skipped
Message : “No frames were lip-synced, so the video is unchanged.”
Résolution : Utilisez une vidéo où le visage du locuteur est bien visible, puis soumettez à nouveau.
Erreurs système et de traitement
generation_pipeline_failed
Message : “The generation failed while processing. Please try again or contact support if this keeps happening.”
Description : Cette erreur indique un échec dans l’une des étapes de traitement internes du pipeline de génération.
Résolution :
- Vérifiez que vos données d’entrée respectent toutes les spécifications requises.
- Essayez de soumettre à nouveau la requête, car certaines erreurs de pipeline peuvent être temporaires.
- Si le problème continue, contactez notre équipe support avec des détails sur votre requête et le message d’erreur précis pour une analyse plus poussée.
generation_unknown_error
Message : “Something went wrong while processing this generation. Please try again.”
Description : La génération a échoué pour une raison qui n’a pas de code plus précis.
Résolution :
- Relancez la génération.
- Si elle échoue de façon répétée, contactez le support avec l’ID de génération.
generation_infra_storage_error
Message : “An error occurred while accessing the storage on infra layer.”
Description : Cette erreur indique un problème d’accès ou de gestion des ressources de stockage pendant le processus de génération. Elle peut survenir à cause de problèmes temporaires du service de stockage ou de problèmes de connectivité.
Résolution :
- Relancez votre requête après un court délai, car les erreurs de stockage sont souvent temporaires.
- Assurez-vous que vos fichiers d’entrée sont accessibles et non corrompus.
- Si le problème persiste, contactez notre équipe support, car il peut s’agir d’un problème d’infrastructure plus large.
generation_infra_resource_exhausted
Message : “The infra resources are exhausted.”
Description : Cette erreur survient quand les ressources d’infrastructure nécessaires au traitement de votre requête sont temporairement indisponibles ou saturées.
Résolution :
- Attendez quelques minutes et relancez votre requête, car la disponibilité des ressources fluctue.
- Envisagez de soumettre votre requête en heures creuses, quand les ressources sont plus disponibles.
- Si vous rencontrez souvent cette erreur, contactez notre équipe support pour discuter de vos habitudes d’usage et des solutions possibles.
generation_infra_service_unavailable
Message : “The infra service is unavailable.”
Description : Cette erreur indique qu’un ou plusieurs services d’infrastructure nécessaires au traitement sont temporairement indisponibles. Cela peut être dû à une maintenance, à des problèmes de connectivité ou à des pannes de service.
Résolution :
- Consultez notre page de statut pour voir s’il y a des problèmes de service ou des fenêtres de maintenance en cours.
- Relancez votre requête après un court délai, car les problèmes de disponibilité de service sont généralement temporaires.
- Si le service reste indisponible pendant une période prolongée, contactez notre équipe support pour obtenir des nouvelles et de l’aide.
Conseils généraux de dépannage
- Vérifiez votre clé API : assurez-vous d’utiliser la bonne clé API et qu’elle n’a pas été révoquée.
- Vérifiez le format de la requête : contrôlez que votre requête API est correctement formatée et inclut tous les paramètres requis.
- Consultez les limites de débit : assurez-vous de ne pas avoir dépassé vos limites de débit API.
- Vérifiez l’état du service : consultez notre page de statut pour voir s’il y a des problèmes de service en cours.
- Consultez la documentation : notre documentation API a peut-être été mise à jour avec de nouvelles informations ou des changements.
Signaler une erreur peu claire ou un contournement
Si une erreur n’indiquait pas quoi corriger, si un résultat était incorrect ou si vous avez eu besoin d’un contournement, signalez-le avec Submit Feedback (POST /v2/feedback).
- Envoyez un signalement par problème, avec un
kind(confusing_error,bug,missing_capability,workaround,docsouother) et unmessagede 4 000 caractères maximum qui inclut le texte exact de l’erreur. - Ajoutez l’
errorCodeet legenerationIdquand vous les avez. - L’équipe sync. examine les signalements tous les jours.
- L’appel renvoie
202avec unidde référence, ne modifie ni ne relance aucune tâche, et est limité à 30 signalements par minute. - Le serveur MCP expose le même signalement via l’outil
feedback_send.
Trouver les ID de génération depuis Studio
Si vous avez besoin de trouver un ID de génération pour le dépannage, vous pouvez facilement le retrouver dans l’interface de Studio. Les modes Studio Pro et Studio Lite suivent le même processus de base :
Pour le mode Studio Pro : cliquez d’abord sur le bouton “History” dans l’interface de Studio, puis suivez les étapes ci-dessous.
Pour le mode Studio Lite : passez directement aux étapes ci-dessous.
- Repérez votre génération : trouvez la miniature de la génération dont vous avez besoin de l’ID
- Ouvrez le menu : survolez la miniature de la génération et cliquez sur le menu à trois points qui apparaît
- Copiez le Job ID : sélectionnez “copy job id” dans le menu déroulant
Pour Agent Mode : dans Agent Mode, vous pouvez trouver les ID de génération de deux façons :
- Barre latérale Sessions : cliquez sur le menu déroulant (trois points) à côté d’une session dans la barre latérale et sélectionnez “Copy Job ID”
- Carte d’erreur : quand une génération échoue, cliquez directement sur le bouton “Copy Job ID” de la carte de notification d’erreur
Cet ID de génération peut ensuite être utilisé pour contacter le support ou pour effectuer des appels API afin de récupérer les détails d’une génération précise.
Si vous rencontrez toujours des problèmes après ces étapes, consultez la page Troubleshooting pour les problèmes courants et leurs solutions, ou contactez notre équipe support.
Ressources associées
- Limites de débit: comprenez les limites de débit de l’API et comment gérer les requêtes limitées
- Webhooks: recevez des notifications en temps réel quand des tâches de génération se terminent ou échouent
- Démarrage rapide: lancez votre premier appel à l’API sync. labs
Base de connaissances du support
- Internal Server Error pendant le lipsync: dépannage des échecs de pipeline
- Internal Server Error pendant le TTS: erreurs propres au TTS
- Dépannage des uploads: erreurs d’upload de fichiers
- Unable to process audio: erreurs de traitement audio
- Unexpected error occurred: dépannage des erreurs générales
Questions fréquentes
Que signifie l’erreur 400 ?
Une erreur 400 signifie que votre requête contient une entrée invalide. Causes fréquentes : URL mal formée, format de média non pris en charge, champs requis manquants ou valeur hors de la plage autorisée. Un média plus long que ce que votre forfait autorise est rejeté avec 402 generation_plan_duration_exceeded, pas 400. Consultez le code d’erreur précis dans le corps de la réponse pour savoir quoi corriger.
Pourquoi ma génération reste-t-elle bloquée en PENDING ?
Une génération au statut PENDING attend des ressources de traitement. En période de forte demande, les tâches peuvent patienter brièvement en file avant de démarrer. Si une génération reste longtemps en PENDING, interrogez son ID existant ou contactez le support. Ne créez pas de génération de remplacement simplement parce qu’elle est encore en attente.
Comment relancer des générations en échec ?
Quand une génération se termine en FAILED ou REJECTED, relancez avec la même clé et les mêmes entrées : la relance démarre une nouvelle génération, admise et facturée comme une première requête. Pour un timeout ou un résultat de soumission inconnu, gardez la clé et les entrées d’origine ; ne lancez pas de remplacement. Consultez Requêtes idempotentes.

