Erreurs
L’API utilise les codes HTTP usuels. Une réponse 2xx est un succès ; les autres portent un
message lisible.
{ "detail": "Format non supporté: .xyz. Utilisez: …" }
Le champ detail contient le message (en français) ; certaines réponses ajoutent error et
request_id. Affichez detail à vos utilisateurs plutôt que de le deviner à partir du code.
Codes
| Code | Signification | Que faire |
|---|---|---|
400 | Requête invalide (fichier vide, paramètre mal formé). | Corriger la requête. |
401 | Clé API absente, invalide ou révoquée. Ou en-tête Authorization: Bearer envoyé sur ce domaine. | Vérifier X-API-Key. Voir Authentification. |
402 | Quota mensuel et crédit insuffisants. | Recharger ou changer d’offre. Voir Quotas et tarifs. |
403 | Ressource qui n’est pas à vous, compte suspendu, ou rôle insuffisant. | Vérifier l’identifiant utilisé. |
404 | Ressource inconnue (transcription, tâche, clé) ou route inexistante. | Vérifier l’identifiant et l’URL. |
413 | Fichier trop volumineux pour cette route. | Passer par l’envoi direct. |
415 | Format de fichier non pris en charge. | Convertir le fichier. |
422 | Données comprises mais refusées : langue inconnue, lien non accepté, audio illisible. | Lire detail. |
429 | Trop de tentatives sur une route sensible (par exemple la connexion d’un terminal). | Attendre quelques minutes. |
5xx | Erreur de notre côté, ou service momentanément indisponible. | Réessayer avec un délai croissant. |
Un job asynchrone qui échoue
Pour un job lancé par POST /v1/transcribe-url, l’erreur n’est pas un code HTTP mais le statut
du job : GET /v1/tasks/{task_id} répond 200 avec "status": "error" et le motif dans error.
{ "task_id": "9f8e7d6c", "status": "error", "error": "Fichier illisible ou sans piste audio." }
Réessayer sans risque
- Une requête de lecture (
GET) peut toujours être rejouée. POST /v1/transcribeetPOST /v1/transcribe-urlcréent une transcription à chaque appel (et consomment du quota). Si vous n’avez pas reçu de réponse, vérifiez d’abord l’historique (GET /v1/transcriptions) avant de renvoyer.- Sur une erreur
5xxou une coupure réseau, attendez 1, 2, 4 secondes… entre les essais.
Connexion d’un terminal
La route POST /v1/auth/device/token suit la norme OAuth (RFC 8628) et répond avec
{"error": "…"} : authorization_pending (continuez d’attendre), slow_down (ralentissez),
access_denied (refusé dans le navigateur), expired_token (code expiré, recommencez),
invalid_grant (code inconnu ou déjà utilisé). Le SDK s’en charge pour vous.