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 projet n’est pas dans un état qui permet la requête
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 - La transcription n’a pas pu aboutir

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`	La transcription n’a pas pu aboutir
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	`INVALID_TRANSLATED_SRT`	translatedSrt ne contient pas de répliques SRT valides
400	`TRANSLATED_SRT_CUE_COUNT_MISMATCH`	Le nombre de répliques de translatedSrt et de sourceSrt diffère
409	`DUB_ONLY_REQUIRES_TRANSCRIPTION`	Le projet n’a pas de transcription terminée à doubler
409	`TRANSLATION_ALREADY_IN_PROGRESS`	Un doublage est déjà en cours pour la langue
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 sélectionnée ne figure pas dans le catalogue et n’est pas une voix personnalisée enregistrée par le compte authentifié.
403	`LIPSYNC_MODE_ACCESS_DENIED`	Le mode de synchronisation labiale premium n’est pas disponible sur le forfait

Erreurs asynchrones d’alignement SRT

Ces erreurs surviennent après l’acceptation d’une requête de traduction ou de doublage. Le point de terminaison de statut répond en HTTP 200 avec status: "failed" ; son champ error et le webhook project.translation.failed contiennent uniquement code et message. Les échecs enregistrés utilisent des messages VoiceCheap fixes ; les numéros de répliques et les index de segments ne sont pas inclus. Les erreurs de requête synchrones, dont TRANSLATED_SRT_CUE_COUNT_MISMATCH, restent des HTTP 400 dans le tableau précédent.

Résultat	Code	Signification
`GET` 200 / webhook	`TRANSLATED_SRT_UNMATCHED_CUES`	Une réplique traduite ne correspond à aucun segment de transcription (signalée par le statut et les webhooks)
`GET` 200 / webhook	`TRANSLATED_SRT_MISSING_SEGMENTS`	Un segment de transcription n’a pas de réplique traduite (signalé par le statut et les webhooks)

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.Solution : Vérifiez que votre clé API est correcte et incluse dans l’en-tête x-api-key.

{
  "code": "INVALID_API_KEY",
  "message": "Invalid API key. Please check your API key and try again."
}

SUBSCRIPTION_REQUIRED

Statut HTTP : 403L’accès à l’API et au MCP nécessite un forfait Starter ou supérieur.Solution : Passez à un forfait Starter ou supérieur sur voicecheap.ai.

{
  "code": "SUBSCRIPTION_REQUIRED",
  "message": "A Starter plan or higher is required to use the API and MCP. Please upgrade your account at voicecheap.ai/pricing."
}

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

Autres erreurs d’authentification et d’équipe

HTTP	Code	Description
401	`USER_NOT_FOUND`	Le compte associé à cette clé est introuvable
403	`AMBIGUOUS_TEAM_API_KEY`	Le titulaire de la clé appartient à plusieurs équipes ; contactez l’assistance
403	`TEAM_OWNER_NOT_FOUND`	Le compte du propriétaire de l’équipe associée est introuvable

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 180 minutes. Your video is 181 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."
}

Erreurs d’autorisation et d’utilisation

Statut	Code	Action
401	`API_KEY_EXPIRED`, `INVALID_MCP_TOKEN`	Utilisez une clé valide et non expirée ou reconnectez l’assistant.
403	`INSUFFICIENT_SCOPE`	Accordez l’autorisation nécessaire ou choisissez un autre identifiant.
403	`SUBSCRIPTION_REQUIRED`	Utilisez un forfait Starter ou supérieur.
429	`INTEGRATION_MONTHLY_LIMIT_REACHED`	Attendez la réinitialisation mensuelle ou changez d’abonnement.
429	`INTEGRATION_RATE_LIMIT_REACHED`, `RATE_LIMIT_EXCEEDED`	Attendez avant de réessayer et espacez progressivement les tentatives.
429	`CONCURRENT_TRANSLATION_LIMIT_REACHED`	Attendez qu’une génération en cours se termine.
400	`VALIDATION_ERROR`	Corrigez les arguments à l’aide du schéma d’entrée du catalogue.
404	`UNKNOWN_ACTION`	Utilisez un nom d’action pris en charge obtenu lors de la découverte.

Consultez les règles d’utilisation et les limites pour le quota partagé du compte. Les erreurs ne consomment pas d’appels mensuels. action_request_get, usage_get, projects_status et GET /v1/translate/{projectId}/status sont exemptés du quota mensuel.

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": "The transcription could not be completed. Please try again."
}

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": "The translation could not be completed. Please try again."
}

LIPSYNC_FAILED

Le traitement de la synchronisation labiale a échoué.Causes possibles :

Un problème temporaire pendant la 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 could not be completed. Please try again."
}

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

Découverte

Compte

Utilisation et activité

Paramètres et notifications

Équipe

Projets

Traduction et doublage

Transcriptions et édition

Synthèse vocale

Voix de synthèse

Voix de doublage

Transcription

Sous-titres et légendes

Images

Miniatures

Dossiers

Glossaire

Webhooks

Publication

Statut des requêtes

OAuth et protocole MCP

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 asynchrones d’alignement SRT

Erreurs d’authentification

Autres erreurs d’authentification et d’équipe

Erreurs de validation de fichier

Erreurs de validation

Erreurs de ressource

Erreurs d’autorisation et d’utilisation

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 asynchrones d’alignement SRT

​Erreurs d’authentification

​Autres erreurs d’authentification et d’équipe

​Erreurs de validation de fichier

​Erreurs de validation

​Erreurs de ressource

​Erreurs d’autorisation et d’utilisation

​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 asynchrones d’alignement SRT

Erreurs d’authentification

Autres erreurs d’authentification et d’équipe

Erreurs de validation de fichier

Erreurs de validation

Erreurs de ressource

Erreurs d’autorisation et d’utilisation

Erreurs de traitement

Erreurs serveur

Gestion des erreurs