Gérer les erreurs

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 :

Comprendre pourquoi une requête est refusée

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, too_many_live_sessions, live_capacity, internal_error, service_unavailable, et pour topup_needs_user avec le reason pending ou in_progress. Respectez le délai de Retry-After s'il est présent ; sinon, espacez les tentatives.
• Pour relancer POST /v1/transcriptions ou POST /v1/topups, 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.

Transcription en direct

POST /v1/live/sessions et les autres endpoints en direct utilisent la même enveloppe d'erreur. Les codes invalid_request, unsupported_language, insufficient_minutes et email_not_verified s'y appliquent aussi, avec les codes en direct du tableau ci-dessus. La création d'une session n'est pas idempotente : réessayer après too_many_live_sessions ou live_capacity crée une nouvelle session.

Une fois la session créée, les problèmes arrivent sur le WebSocket sous forme d'événements error et de codes de fermeture, pas d'erreurs HTTP. Tous les événements sont décrits dans Transcription en direct.

Une session en direct qui se termine pour une raison comme balance_exhausted ou idle_timeout n'est pas une erreur : elle envoie session.ended avec un motif de fin et elle est enregistrée. Voir Motifs de fin.

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. Si une traduction échoue, le webhook transcription.translation.failed est envoyé, et la transcription n’échoue jamais pour autant.

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