> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.voicecheap.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Codes d'erreur
> Référence complète des codes d'erreur renvoyés par l'API VoiceCheap
# Codes d'erreur
L'API VoiceCheap utilise des codes de statut HTTP standard et renvoie des réponses d'erreur structurées pour vous aider à gérer les erreurs avec élégance.
## Format de réponse d'erreur
Toutes les réponses d'erreur suivent cette structure :
```json theme={null}
{
"code": "ERROR_CODE",
"message": "Human-readable description of the error"
}
```
Certaines erreurs peuvent inclure des champs supplémentaires. Les échecs de validation de la charge utile de la requête renvoient une entrée par
champ invalide dans `details`, et `field` est omis lorsque le message de contrainte ne nomme pas une
propriété spécifique :
```json theme={null}
{
"code": "VALIDATION_ERROR",
"message": "Request validation failed.",
"details": [
{
"field": "outputFormat",
"messages": ["outputFormat must be one of the following values: json, srt, vtt"]
}
]
}
```
## Codes d'état HTTP
| Code d'état | Signification |
| ----------- | -------------------------------------------------------------------- |
| 200 | **OK** - La requête a réussi |
| 400 | **Bad Request** - Paramètres invalides ou erreur de validation |
| 401 | **Unauthorized** - Clé API invalide ou manquante |
| 403 | **Forbidden** - Clé API valide mais autorisations insuffisantes |
| 404 | **Not Found** - La ressource n'existe pas |
| 409 | **Conflict** - Le résultat demandé n'est pas prêt |
| 413 | **Payload Too Large** - Le fichier téléchargé dépasse sa limite |
| 429 | **Too Many Requests** - Limite de débit dépassée |
| 500 | **Internal Server Error** - Quelque chose a mal tourné de notre côté |
| 502 | **Bad Gateway** - Un moteur de traitement a échoué |
## Erreurs de transcription et d'exportation de transcription
| État | Code | Signification |
| ---- | --------------------------- | --------------------------------------------------------------------------------------- |
| 400 | `INVALID_MEDIA_STREAM` | Le média téléchargé ne contient pas de flux audio |
| 400 | `DURATION_TOO_LONG` | Le média de transcription autonome dépasse deux heures |
| 400 | `INVALID_BRAND_VOCABULARY` | Une entrée de glossaire spécifique à la requête dépasse les limites |
| 400 | `TARGET_LANGUAGE_REQUIRED` | Une requête de transcription traduite a omis sa langue |
| 404 | `TRANSCRIPT_NOT_FOUND` | La transcription originale ou traduite demandée est absente |
| 409 | `TRANSCRIPT_NOT_READY` | La transcription demandée est toujours en cours de traitement |
| 502 | `TRANSCRIPTION_EMPTY` | La transcription ne contenait aucune parole utilisable |
| 502 | `TRANSCRIPTION_FAILED` | Le moteur de transcription n'a pas pu terminer la requête |
| 400 | `INVALID_MULTIPART_REQUEST` | La requête de téléchargement en plusieurs parties est mal formée ou dépasse les limites |
## Erreurs d'option de doublage
| État | Code | Signification |
| ---- | ----------------------------------------------- | ------------------------------------------------------------------------------ |
| 400 | `INVALID_SOURCE_SRT` | sourceSrt ne contient pas de repères SRT valides |
| 400 | `SOURCE_LANGUAGE_REQUIRED_FOR_SRT` | sourceSrt nécessite une originalLanguage explicite |
| 400 | `VOICE_ID_REQUIRED` | Le mode voix personnalisées nécessite un ID de voix |
| 400 | `VOICE_ID_NOT_ALLOWED_WITH_CLONING` | voiceId a été combiné avec le clonage vocal |
| 400 | `VOICE_CLONING_SETTINGS_NOT_ALLOWED` | Les paramètres de clonage ont été combinés avec le mode voix personnalisées |
| 400 | `CONFLICTING_LIPSYNC_OPTIONS` | Les champs de synchronisation labiale modernes et hérités sont en conflit |
| 400 | `TRANSLATION_TIME_SKIP_REQUIRES_BACKGROUND` | Les sauts temporels nécessitent un audio d’arrière-plan |
| 400 | `TRANSLATION_TIME_SKIP_CONFLICT` | Les sauts temporels sont en conflit avec la conservation de la voix originale |
| 400 | `TRANSLATION_TIME_SKIP_OUT_OF_RANGE` | Un saut temporel dépasse la durée du média |
| 400 | `INVALID_TRANSLATION_TIME_SKIPS` | Un saut temporel chevauche un segment de transcription |
| 400 | `SUBTITLES_NOT_AVAILABLE_FOR_AUDIO` | Les sous-titres incrustés nécessitent une entrée vidéo |
| 400 | `LIPSYNC_NOT_AVAILABLE_FOR_AUDIO` | La synchronisation labiale nécessite une entrée vidéo |
| 400 | `TRANSLATION_TIME_SKIP_NOT_AVAILABLE_FOR_AUDIO` | Les sauts temporels de traduction nécessitent une entrée vidéo |
| 403 | `CUSTOM_VOICE_ACCESS_DENIED` | La voix personnalisée n'appartient pas au propriétaire effectif |
| 403 | `LIPSYNC_MODE_ACCESS_DENIED` | Le mode de synchronisation labiale premium n'est pas disponible sur le forfait |
## Erreurs d'authentification
**Statut HTTP :** 401
L'en-tête `x-api-key` n'a pas été fourni.
**Solution :** Incluez votre clé API dans l'en-tête `x-api-key`.
```json theme={null}
{
"code": "MISSING_API_KEY",
"message": "API key is required. Please provide your API key in the x-api-key header."
}
```
**Statut HTTP :** 401
La clé API n'utilise pas le préfixe `vc_` attendu.
**Solution :** Vérifiez que vous avez copié la clé complète depuis l'application VoiceCheap.
```json theme={null}
{
"code": "INVALID_API_KEY_FORMAT",
"message": "Invalid API key format. API keys must start with \"vc_\"."
}
```
**Statut HTTP :** 401
La clé API fournie est invalide ou a expiré.
**Solution :** Vérifiez que votre clé API est correcte et incluse dans l'en-tête `x-api-key`.
```json theme={null}
{
"code": "INVALID_API_KEY",
"message": "The provided API key is invalid. Please check your API key and try again."
}
```
**Statut HTTP :** 403
Le compte possède une clé valide, mais l'accès à l'API n'est pas activé pour ce compte.
**Solution :** Demandez l'accès à l'API ou utilisez un compte pour lequel l'accès à l'API est déjà activé.
```json theme={null}
{
"code": "API_ACCESS_REQUIRED",
"message": "API access is required. Please request access to the API beta program."
}
```
**Statut HTTP :** 403
L'accès à l'API nécessite un abonnement payant actif.
**Solution :** Passez à un forfait payant sur [voicecheap.ai](https://voicecheap.ai/pricing).
```json theme={null}
{
"code": "SUBSCRIPTION_REQUIRED",
"message": "API access requires an active paid subscription. Please upgrade your plan."
}
```
**Statut HTTP :** 403
Votre compte ne dispose pas de suffisamment de crédits pour traiter cette demande.
**Solution :** Achetez plus de crédits ou mettez à niveau votre plan d'abonnement.
```json theme={null}
{
"code": "INSUFFICIENT_CREDITS",
"message": "Insufficient credits to process this file. Please add more credits to your account."
}
```
## Erreurs de validation de fichier
**Statut HTTP :** 400
Aucun fichier n'a été téléchargé avec la demande.
**Solution :** Incluez un fichier dans le champ `file` de vos données de formulaire multipart.
```json theme={null}
{
"code": "FILE_REQUIRED",
"message": "A video or audio file is required. Please upload a file with your request."
}
```
**Statut HTTP :** 400
Le type de fichier téléchargé n'est pas pris en charge.
**Solution :** Téléchargez un fichier dans l'un des formats pris en charge (MP4, MOV, MKV, WebM, MPEG, MP3, WAV, M4A, FLAC, OGG, AAC).
```json theme={null}
{
"code": "INVALID_FILE_TYPE",
"message": "Invalid file type \"application/pdf\". Supported formats: video/mp4, video/quicktime, ..."
}
```
**Statut HTTP :** 413
Le fichier téléchargé dépasse la limite autorisée pour l'abonnement authentifié : Beginner 5 Go, Starter 10 Go, Creator 20 Go, Pro 30 Go, Scale 40 Go, ou Enterprise 60 Go.
**Solution :** Vérifiez la limite de votre forfait, puis compressez le fichier, divisez-le en segments plus petits ou mettez à niveau votre forfait.
```json theme={null}
{
"code": "FILE_TOO_LARGE",
"message": "File size exceeds the 5GB limit for the beginner plan.",
"maximumFileSizeBytes": 5368709120
}
```
**Statut HTTP :** 400
Impossible de détecter la durée du fichier téléchargé.
**Solution :** Assurez-vous que le fichier est un fichier vidéo ou audio valide et non corrompu.
```json theme={null}
{
"code": "DURATION_DETECTION_FAILED",
"message": "Could not detect the duration of the uploaded file. Please ensure the file is a valid video or audio file."
}
```
## Erreurs de validation
**Statut HTTP :** 400
La langue cible spécifiée n'est pas prise en charge.
**Solution :** Utilisez l'une des [langues prises en charge](/docs/fr/introduction#supported-languages).
```json theme={null}
{
"code": "VALIDATION_ERROR",
"message": "Invalid target language. Allowed languages: arabic, brazilian portuguese, british english, ..."
}
```
**Statut HTTP :** 400
Un paramètre booléen a reçu une valeur invalide.
**Solution :** Utilisez `true` ou `false` (sous forme de chaînes dans form-data).
```json theme={null}
{
"code": "INVALID_BOOLEAN_VALUE",
"message": "Invalid boolean value for \"keepBackgroundMusic\". Expected \"true\" or \"false\", got \"yes\"."
}
```
**Statut HTTP :** 400
Un paramètre JSON n'a pas pu être analysé.
**Solution :** Assurez-vous que la chaîne JSON est correctement formatée.
```json theme={null}
{
"code": "INVALID_JSON_FORMAT",
"message": "Invalid JSON format for \"voiceCloningSettings\". Please provide valid JSON."
}
```
**Statut HTTP :** 400
Un champ numérique optionnel de form-data n'était pas un nombre valide. Envoyez une valeur numérique comprise dans la plage documentée.
**Statut HTTP :** 400
La synchronisation labiale a été demandée pour un média dépassant la durée prise en charge pour la synchronisation labiale.
**Solution :** Omettez `lipsyncPro` pour cette requête, ou soumettez un fichier média respectant la limite de synchronisation labiale.
```json theme={null}
{
"code": "LIPSYNC_VIDEO_TOO_LONG",
"message": "LipSync supports up to 30 minutes. Your video is 45 minutes long."
}
```
## Erreurs de ressource
**Statut HTTP :** 404
Le projet spécifié n'existe pas.
**Solution :** Vérifiez que l'identifiant du projet est correct.
```json theme={null}
{
"code": "PROJECT_NOT_FOUND",
"message": "Project with ID 'abc123' not found."
}
```
**Statut HTTP :** 403
Vous n'avez pas l'autorisation d'accéder à cette ressource.
**Solution :** Assurez-vous d'utiliser la clé API correcte pour ce projet.
```json theme={null}
{
"code": "FORBIDDEN",
"message": "You do not have permission to access this project."
}
```
## Limitation du débit
**Statut HTTP :** 429
Vous avez dépassé la limite de débit pour ce point de terminaison.
**Solution :** Patientez avant d'effectuer d'autres requêtes. Utilisez une stratégie d'attente exponentielle.
| Point de terminaison | Limite de débit |
| ------------------------------- | ---------------------- |
| `POST /v1/translate` | 10 requêtes par minute |
| `POST /v1/projects` | 10 requêtes par minute |
| `GET /v1/translate/{id}/status` | 30 requêtes par minute |
| `GET /v1/projects/{id}` | 20 requêtes par minute |
| `DELETE /v1/translate/{id}` | 10 requêtes par minute |
```json theme={null}
{
"code": "RATE_LIMIT_EXCEEDED",
"message": "Too many requests. Please wait before trying again."
}
```
**Statut HTTP :** 429
Vous avez déjà atteint le nombre maximal de traductions en cours d'exécution en parallèle.
**Solution :** Attendez qu'une de vos traductions en cours se termine, puis réessayez la requête.
```json theme={null}
{
"code": "CONCURRENT_TRANSLATION_LIMIT_REACHED",
"message": "Concurrent translation limit reached. You can run up to 10 translations at the same time."
}
```
## Erreurs de traitement
Ces erreurs peuvent être renvoyées dans le champ `error` lors de la vérification du statut de la traduction :
L'audio n'a pas pu être transcrit.
**Causes possibles :**
* La qualité audio est trop faible
* Aucune parole détectée dans l'audio
* Encodage audio non pris en charge
```json theme={null}
{
"code": "TRANSCRIPTION_FAILED",
"message": "Could not transcribe the audio. Please ensure the audio quality is sufficient."
}
```
La transcription n'a pas pu être traduite.
**Causes possibles :**
* Paire de langues non prise en charge
* Le contenu n'a pas pu être traité
```json theme={null}
{
"code": "TRANSLATION_FAILED",
"message": "Failed to translate the content. Please try again."
}
```
La synthèse vocale a échoué pendant le doublage.
**Causes possibles :**
* Le clonage vocal a échoué
* Erreur de génération audio
```json theme={null}
{
"code": "VOICE_SYNTHESIS_FAILED",
"message": "Failed to generate the dubbed audio. Please try again."
}
```
Le traitement de la synchronisation labiale a échoué.
**Causes possibles :**
* Erreur du fournisseur de synchronisation labiale
* Média invalide ou non pris en charge
* La requête a été rejetée ou annulée
```json theme={null}
{
"code": "LIPSYNC_FAILED",
"message": "Lip sync failed."
}
```
## Erreurs serveur
**Statut HTTP :** 500
Une erreur inattendue s'est produite sur nos serveurs.
**Solution :** Réessayez la requête. Si le problème persiste, contactez le support.
```json theme={null}
{
"code": "INTERNAL_ERROR",
"message": "An unexpected error occurred. Please try again later."
}
```
## Gestion des erreurs
```javascript JavaScript theme={null}
try {
const response = await fetch('https://api.voicecheap.ai/v1/translate', {
method: 'POST',
headers: { 'x-api-key': apiKey },
body: formData,
});
if (!response.ok) {
const error = await response.json();
switch (error.code) {
case 'MISSING_API_KEY':
case 'INVALID_API_KEY':
case 'INVALID_API_KEY_FORMAT':
// Check API key configuration
break;
case 'INSUFFICIENT_CREDITS':
// Prompt user to add credits
break;
case 'RATE_LIMIT_EXCEEDED':
// Implement backoff and retry
break;
case 'CONCURRENT_TRANSLATION_LIMIT_REACHED':
// Wait for an in-progress translation to finish
break;
default:
// Handle other errors
console.error(`Error: ${error.message}`);
}
}
} catch (err) {
// Handle network errors
console.error(err);
}
```
```python Python theme={null}
import requests
from requests.exceptions import RequestException
try:
response = requests.post(
'https://api.voicecheap.ai/v1/translate',
headers={'x-api-key': api_key},
files=files,
data=data
)
if response.status_code != 200:
error = response.json()
if error['code'] in ['MISSING_API_KEY', 'INVALID_API_KEY', 'INVALID_API_KEY_FORMAT']:
# Check API key configuration
pass
elif error['code'] == 'INSUFFICIENT_CREDITS':
# Prompt user to add credits
pass
elif error['code'] == 'RATE_LIMIT_EXCEEDED':
# Implement backoff and retry
pass
elif error['code'] == 'CONCURRENT_TRANSLATION_LIMIT_REACHED':
# Wait for an in-progress translation to finish
pass
else:
print(f"Error: {error['message']}")
except RequestException as e:
# Handle network errors
print(f"Network error: {e}")
```