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 :

{
  "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 :

{
  "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

MISSING_API_KEY

Statut HTTP : 401L’en-tête x-api-key n’a pas été fourni.Solution : Incluez votre clé API dans l’en-tête x-api-key.

{
  "code": "MISSING_API_KEY",
  "message": "API key is required. Please provide your API key in the x-api-key header."
}

INVALID_API_KEY_FORMAT

Statut HTTP : 401La 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.

{
  "code": "INVALID_API_KEY_FORMAT",
  "message": "Invalid API key format. API keys must start with \"vc_\"."
}

INVALID_API_KEY

Statut HTTP : 401La 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.

{
  "code": "INVALID_API_KEY",
  "message": "The provided API key is invalid. Please check your API key and try again."
}

API_ACCESS_REQUIRED

Statut HTTP : 403Le 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é.

{
  "code": "API_ACCESS_REQUIRED",
  "message": "API access is required. Please request access to the API beta program."
}

SUBSCRIPTION_REQUIRED

Statut HTTP : 403L’accès à l’API nécessite un abonnement payant actif.Solution : Passez à un forfait payant sur voicecheap.ai.

{
  "code": "SUBSCRIPTION_REQUIRED",
  "message": "API access requires an active paid subscription. Please upgrade your plan."
}

INSUFFICIENT_CREDITS

Statut HTTP : 403Votre 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.

{
  "code": "INSUFFICIENT_CREDITS",
  "message": "Insufficient credits to process this file. Please add more credits to your account."
}

Erreurs de validation de fichier

FILE_REQUIRED

Statut HTTP : 400Aucun 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.

{
  "code": "FILE_REQUIRED",
  "message": "A video or audio file is required. Please upload a file with your request."
}

INVALID_FILE_TYPE

Statut HTTP : 400Le 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).

{
  "code": "INVALID_FILE_TYPE",
  "message": "Invalid file type \"application/pdf\". Supported formats: video/mp4, video/quicktime, ..."
}

FILE_TOO_LARGE

Statut HTTP : 413Le 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.

{
  "code": "FILE_TOO_LARGE",
  "message": "File size exceeds the 5GB limit for the beginner plan.",
  "maximumFileSizeBytes": 5368709120
}

DURATION_DETECTION_FAILED

Statut HTTP : 400Impossible 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.

{
  "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

INVALID_TARGET_LANGUAGE

Statut HTTP : 400La langue cible spécifiée n’est pas prise en charge.Solution : Utilisez l’une des langues prises en charge.

{
  "code": "VALIDATION_ERROR",
  "message": "Invalid target language. Allowed languages: arabic, brazilian portuguese, british english, ..."
}

INVALID_BOOLEAN_VALUE

Statut HTTP : 400Un paramètre booléen a reçu une valeur invalide.Solution : Utilisez true ou false (sous forme de chaînes dans form-data).

{
  "code": "INVALID_BOOLEAN_VALUE",
  "message": "Invalid boolean value for \"keepBackgroundMusic\". Expected \"true\" or \"false\", got \"yes\"."
}

INVALID_JSON_FORMAT

Statut HTTP : 400Un paramètre JSON n’a pas pu être analysé.Solution : Assurez-vous que la chaîne JSON est correctement formatée.

{
  "code": "INVALID_JSON_FORMAT",
  "message": "Invalid JSON format for \"voiceCloningSettings\". Please provide valid JSON."
}

INVALID_NUMBER_VALUE

Statut HTTP : 400Un champ numérique optionnel de form-data n’était pas un nombre valide. Envoyez une valeur numérique comprise dans la plage documentée.

LIPSYNC_VIDEO_TOO_LONG

Statut HTTP : 400La 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.

{
  "code": "LIPSYNC_VIDEO_TOO_LONG",
  "message": "LipSync supports up to 30 minutes. Your video is 45 minutes long."
}

Erreurs de ressource

PROJECT_NOT_FOUND

Statut HTTP : 404Le projet spécifié n’existe pas.Solution : Vérifiez que l’identifiant du projet est correct.

{
  "code": "PROJECT_NOT_FOUND",
  "message": "Project with ID 'abc123' not found."
}

FORBIDDEN

Statut HTTP : 403Vous n’avez pas l’autorisation d’accéder à cette ressource.Solution : Assurez-vous d’utiliser la clé API correcte pour ce projet.

{
  "code": "FORBIDDEN",
  "message": "You do not have permission to access this project."
}

Limitation du débit

RATE_LIMIT_EXCEEDED

Statut HTTP : 429Vous 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

{
  "code": "RATE_LIMIT_EXCEEDED",
  "message": "Too many requests. Please wait before trying again."
}

CONCURRENT_TRANSLATION_LIMIT_REACHED

Statut HTTP : 429Vous 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.

{
  "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 :

TRANSCRIPTION_FAILED

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

{
  "code": "TRANSCRIPTION_FAILED",
  "message": "Could not transcribe the audio. Please ensure the audio quality is sufficient."
}

TRANSLATION_FAILED

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é

{
  "code": "TRANSLATION_FAILED",
  "message": "Failed to translate the content. Please try again."
}

VOICE_SYNTHESIS_FAILED

La synthèse vocale a échoué pendant le doublage.Causes possibles :

Le clonage vocal a échoué
Erreur de génération audio

{
  "code": "VOICE_SYNTHESIS_FAILED",
  "message": "Failed to generate the dubbed audio. Please try again."
}

LIPSYNC_FAILED

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

{
  "code": "LIPSYNC_FAILED",
  "message": "Lip sync failed."
}

Erreurs serveur

INTERNAL_ERROR

Statut HTTP : 500Une erreur inattendue s’est produite sur nos serveurs.Solution : Réessayez la requête. Si le problème persiste, contactez le support.

{
  "code": "INTERNAL_ERROR",
  "message": "An unexpected error occurred. Please try again later."
}

Gestion des erreurs

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);
}

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}")

Vue d’ensemble

Transcription

Traduction

Référence

Codes d'erreur

Codes d’erreur

Format de réponse d’erreur

Codes d’état HTTP

Erreurs de transcription et d’exportation de transcription

Erreurs d’option de doublage

Erreurs d’authentification

Erreurs de validation de fichier

Erreurs de validation

Erreurs de ressource

Limitation du débit

Erreurs de traitement

Erreurs serveur

Gestion des erreurs

​Codes d’erreur

​Format de réponse d’erreur

​Codes d’état HTTP

​Erreurs de transcription et d’exportation de transcription

​Erreurs d’option de doublage

​Erreurs d’authentification

​Erreurs de validation de fichier

​Erreurs de validation

​Erreurs de ressource

​Limitation du débit

​Erreurs de traitement

​Erreurs serveur

​Gestion des erreurs

Codes d’erreur

Format de réponse d’erreur

Codes d’état HTTP

Erreurs de transcription et d’exportation de transcription

Erreurs d’option de doublage

Erreurs d’authentification

Erreurs de validation de fichier

Erreurs de validation

Erreurs de ressource

Limitation du débit

Erreurs de traitement

Erreurs serveur

Gestion des erreurs