Gérer les erreurs | transcript1 docs

L'API peut refuser votre requête, ou l'accepter avant que la transcription échoue pendant le traitement. Dans ce second cas, l'objet transcription passe au statut failed. Ces deux situations se traitent différemment.

Lire une réponse d'erreur

Quand une requête /v1 est refusée, l'API renvoie toujours cette structure :

{
  "error": {
    "code": "insufficient_minutes",
    "message": "Not enough minutes",
    "retryable": false,
    "action_url": "https://transcript1.com/dashboard/billing",
    "minutes_needed": 20,
    "minutes_remaining": 3
  }
}

Dans votre code, utilisez code pour décider quoi faire. Réservez message à l'affichage : sa formulation peut évoluer. Si retryable vaut true, vous pouvez réessayer la même requête plus tard.

Selon l'erreur, d'autres champs complètent retryable :

Champ	Erreur concernée	À quoi il sert
`action_url`	`insufficient_minutes`	Lien pour souscrire une offre ou acheter une recharge.
`minutes_needed`, `minutes_remaining`	`insufficient_minutes`	Nombre de minutes nécessaires et solde disponible. Le premier vaut `null` tant que la durée nécessaire est inconnue.
`supported_platforms`	`unsupported_platform`	Liste des plateformes acceptées : `["youtube", "x", "tiktok", "instagram", "facebook", "bluesky", "twitch", "dailymotion", "pinterest", "linkedin", "snapchat"]`.
`missing_chunks`	`upload_incomplete`	Index des blocs que le serveur n'a pas reçus.
`max_bytes`	`media_too_large`	Taille maximale de fichier autorisée pour votre compte, en octets.
`params`	`invalid_request`	Objet qui indique, champ par champ, les erreurs de validation du corps ou des paramètres d'URL.

Comprendre pourquoi une requête est refusée

Statut HTTP	`code`	Réessayer tel quel ?	Cause et action
400, 422	`invalid_request`	Non	Il manque un champ, sa valeur est invalide ou le corps n'est pas un JSON valide. Certaines associations sont aussi interdites, comme `diarize` avec `source: "captions"`, ou `reuse_recent` avec `webhook_url`.
422	`invalid_url`	Non	Le lien ne convient pas, ou `platform` ne correspond pas à sa plateforme. Utilisez le lien d'une vidéo sur YouTube, X, TikTok, Instagram, Facebook, Bluesky ou une autre plateforme de la page Sources et options.
422	`unsupported_platform`	Non	La valeur de `platform` ne désigne pas une plateforme acceptée.
422	`unsupported_media`	Non	L'extension du fichier importé n'est pas acceptée.
401	`unauthorized`	Non	Les informations d'authentification manquent, sont invalides, ont expiré ou ont été révoquées. Pour un import, le token peut aussi être invalide ou expiré.
403	`insufficient_scope`	Non	Le token OAuth ne dispose pas de la permission `transcriptions:read` ou `transcriptions:write` nécessaire.
403	`email_not_verified`	Non	Vous devez vérifier votre adresse e-mail avant de créer une transcription.
402	`insufficient_minutes`	Non	Votre solde est à 0, ou il ne couvre pas la durée à transcrire.
402	`no_active_plan`	Non	L'achat d'une recharge exige une offre payante active. L'endpoint de facturation du tableau de bord renvoie ce code, pas les endpoints de transcription.
404	`not_found`	Non	La transcription n'existe pas ou appartient à une autre équipe.
409	`upload_incomplete`	Non	Envoyez les blocs manquants, puis appelez à nouveau la validation de l'import.
409	`invalid_state`	Non	La transcription n'est plus en attente d'import. Vous ne pouvez donc plus envoyer de blocs ni valider l'envoi.
409	`idempotency_conflict`	Non	Vous avez déjà utilisé cette `Idempotency-Key` avec d'autres paramètres.
413	`media_too_large`	Non	Le fichier est trop volumineux pour la limite de votre compte. Consultez Imports de fichiers.
413	`invalid_request`	Non	Le corps JSON dépasse 1 Mo. Pour un fichier trop volumineux, l'erreur serait `media_too_large`.
429	`rate_limited`	Oui	Vous avez envoyé trop de requêtes par minute. Attendez le nombre de secondes indiqué dans `Retry-After`.
429	`too_many_active_jobs`	Oui	Trop de transcriptions sont en cours, ou trop d'imports sont ouverts. Attendez le nombre de secondes indiqué dans `Retry-After`.
500	`internal_error`	Oui	Une erreur s'est produite sur nos serveurs. Réessayez dans un instant.
503	`service_unavailable`	Oui	transcript1 est temporairement indisponible. Réessayez dans un instant.

Si votre navigateur s'authentifie avec un cookie de connexion plutôt qu'un token bearer, l'API vérifie aussi l'origine de la requête. Un appel depuis un autre site reçoit 403 forbidden_origin. Ce contrôle ne concerne pas les appels API qui utilisent l'en-tête Authorization.

Toutes les réponses 429 précisent le délai d'attente en secondes dans Retry-After. Les seuils sont détaillés dans Facturation et limites.

Quand relancer une requête

Relancez une requête inchangée seulement si retryable vaut true. C'est le cas pour rate_limited, too_many_active_jobs, internal_error et service_unavailable. Respectez le délai de Retry-After s'il est présent ; sinon, espacez les tentatives.
Pour relancer POST /v1/transcriptions, gardez le même en-tête Idempotency-Key. Si le premier appel a abouti, vous éviterez ainsi une seconde facturation.
Pour les autres codes, corrigez d'abord la requête.

Si la transcription échoue pendant le traitement

La transcription peut échouer après la réponse à votre requête. Si status vaut failed, l'objet contient error: { "code", "message" }. Lisez le champ error dans les réponses de suivi du traitement ou dans le webhook transcription.failed.

`error.code`	Ce qui s'est passé	Que faire ?
`media_unavailable`	La vidéo n'existe pas ou n'est plus accessible.	Ne relancez pas sans vérifier l'URL.
`media_private`	La vidéo est privée.	Choisissez une publication publique, ou une vidéo YouTube publique ou non répertoriée. Relancer le même lien ne résoudra rien.
`login_required`	Il faut se connecter à la plateforme pour accéder à la vidéo.	Inutile de relancer. L'échec est définitif et l'API ne réessaie pas.
`no_audio`	La vidéo ne contient pas de piste audio.	Inutile de relancer. L'échec est définitif et l'API ne réessaie pas.
`age_restricted`	La plateforme impose une restriction d'âge pour cette vidéo.	Ne relancez pas le lien. Importez le fichier à la place.
`live_stream`	Le direct est en cours ou n'a pas encore commencé.	Attendez la fin du direct avant de relancer.
`no_captions`	Vous avez choisi `captions` pour `source`, mais la vidéo n'a pas de sous-titres utilisables.	Passez à `source: "auto"` ou `"stt"`.
`media_too_long`	L'enregistrement dépasse la limite de 5 heures pour la transcription par IA.	Découpez l'enregistrement avant de l'envoyer à nouveau.
`unsupported_media`	Le fichier est illisible ou ne contient pas de piste audio.	Envoyez un fichier dans un format accepté plutôt que de relancer le même.
`no_speech`	Aucune parole détectée.	Inutile de relancer.
`unsupported_language`	La langue de l'enregistrement n'est pas prise en charge.	Indiquez un code accepté dans `language` ou laissez `"auto"`. Ne relancez pas sans modifier le réglage.
`insufficient_minutes`	Votre solde s'est épuisé avant le décompte des minutes de cette transcription.	Rechargez votre solde, puis relancez.
`fetch_failed`	Le téléchargement du média a échoué malgré plusieurs tentatives.	Vous pouvez réessayer plus tard.
`transcription_failed`	La transcription par IA a échoué malgré plusieurs tentatives.	Vous pouvez réessayer plus tard.

Si une transcription échoue ou si vous l'annulez, vous ne payez rien. Les minutes déjà prélevées vous sont rendues.