# Gérer les erreurs

> Interprétez les réponses d'erreur et les échecs de transcription, et sachez quand relancer une requête.

Canonical: https://transcript1.com/fr/docs/errors
Language: fr
Last updated: 2026-10-19

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 :

```json
{
  "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](https://transcript1.com/fr/docs/sources-and-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](https://transcript1.com/fr/docs/uploads). |
| 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](https://transcript1.com/fr/docs/billing-and-limits).

## 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](https://transcript1.com/fr/docs/webhooks) `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.