Códigos de error

La API VoiceCheap utiliza códigos de estado HTTP estándar y devuelve respuestas de error estructuradas para ayudarle a manejar los errores correctamente.

Formato de respuesta de error

Todas las respuestas de error siguen esta estructura:

{
  "code": "ERROR_CODE",
  "message": "Human-readable description of the error"
}

Algunos errores pueden incluir campos adicionales. Los fallos de validación de la carga útil de la solicitud devuelven una entrada por campo no válido en details, y field se omite cuando el mensaje de restricción no nombra una propiedad específica:

{
  "code": "VALIDATION_ERROR",
  "message": "Request validation failed.",
  "details": [
    {
      "field": "outputFormat",
      "messages": ["outputFormat must be one of the following values: json, srt, vtt"]
    }
  ]
}

Códigos de estado HTTP

Código de estado	Significado
200	OK - La solicitud se realizó correctamente
400	Bad Request - Parámetros no válidos o error de validación
401	Unauthorized - Clave de API no válida o ausente
403	Forbidden - Clave de API válida pero con permisos insuficientes
404	Not Found - El recurso no existe
409	Conflict - El resultado solicitado no está listo
413	Payload Too Large - El archivo cargado supera su límite
429	Too Many Requests - Límite de tasa excedido
500	Internal Server Error - Algo salió mal por nuestra parte
502	Bad Gateway - Un motor de procesamiento falló

Errores de transcripción y exportación de transcripciones

Estado	Código	Significado
400	`INVALID_MEDIA_STREAM`	El medio cargado no contiene una secuencia de audio
400	`DURATION_TOO_LONG`	El medio de transcripción independiente dura más de dos horas
400	`INVALID_BRAND_VOCABULARY`	Una entrada de glosario específica de la solicitud infringe los límites
400	`TARGET_LANGUAGE_REQUIRED`	Una solicitud de transcripción traducida omitió su idioma
404	`TRANSCRIPT_NOT_FOUND`	La transcripción original o traducida solicitada está ausente
409	`TRANSCRIPT_NOT_READY`	La transcripción solicitada aún se está procesando
502	`TRANSCRIPTION_EMPTY`	La transcripción no contenía voz utilizable
502	`TRANSCRIPTION_FAILED`	El motor de transcripción no pudo completar la solicitud
400	`INVALID_MULTIPART_REQUEST`	La solicitud de carga multipart está mal formada o supera los límites

Errores de opciones de doblaje

Estado	Código	Significado
400	`INVALID_SOURCE_SRT`	sourceSrt no contiene señales SRT válidas
400	`SOURCE_LANGUAGE_REQUIRED_FOR_SRT`	sourceSrt requiere un originalLanguage explícito
400	`VOICE_ID_REQUIRED`	El modo de voces personalizadas requiere un ID de voz
400	`VOICE_ID_NOT_ALLOWED_WITH_CLONING`	voiceId se combinó con clonación de voz
400	`VOICE_CLONING_SETTINGS_NOT_ALLOWED`	La configuración de clonación se combinó con el modo de voces personalizadas
400	`CONFLICTING_LIPSYNC_OPTIONS`	Los campos de sincronización labial modernos y heredados no coinciden
400	`TRANSLATION_TIME_SKIP_REQUIRES_BACKGROUND`	Los saltos de tiempo requieren audio de fondo
400	`TRANSLATION_TIME_SKIP_CONFLICT`	Los saltos de tiempo entran en conflicto con la retención de la voz original
400	`TRANSLATION_TIME_SKIP_OUT_OF_RANGE`	Un salto de tiempo se extiende más allá de la duración del medio
400	`INVALID_TRANSLATION_TIME_SKIPS`	Un salto de tiempo se superpone a un segmento de transcripción
400	`SUBTITLES_NOT_AVAILABLE_FOR_AUDIO`	Los subtítulos incrustados requieren entrada de video
400	`LIPSYNC_NOT_AVAILABLE_FOR_AUDIO`	La sincronización labial requiere entrada de video
400	`TRANSLATION_TIME_SKIP_NOT_AVAILABLE_FOR_AUDIO`	Los saltos de tiempo de traducción requieren entrada de video
403	`CUSTOM_VOICE_ACCESS_DENIED`	La voz personalizada no pertenece al propietario efectivo
403	`LIPSYNC_MODE_ACCESS_DENIED`	El modo de sincronización labial premium no está disponible en el plan

Errores de autenticación

MISSING_API_KEY

Estado HTTP: 401No se proporcionó el encabezado x-api-key.Solución: Incluya su clave de API en el encabezado 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

Estado HTTP: 401La clave de API no utiliza el prefijo vc_ esperado.Solución: Compruebe que copió la clave completa desde la aplicación VoiceCheap.

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

INVALID_API_KEY

Estado HTTP: 401La clave de API proporcionada no es válida o ha caducado.Solución: Compruebe que su clave de API sea correcta y esté incluida en el encabezado 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

Estado HTTP: 403La cuenta tiene una clave válida, pero el acceso a la API no está habilitado para esa cuenta.Solución: Solicite acceso a la API o utilice una cuenta que ya tenga el acceso a la API habilitado.

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

SUBSCRIPTION_REQUIRED

Estado HTTP: 403El acceso a la API requiere una suscripción de pago activa.Solución: Actualice a un plan de pago en voicecheap.ai.

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

INSUFFICIENT_CREDITS

Estado HTTP: 403Su cuenta no tiene suficientes créditos para procesar esta solicitud.Solución: Compre más créditos o actualice su plan de suscripción.

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

Errores de validación de archivos

FILE_REQUIRED

Estado HTTP: 400No se cargó ningún archivo con la solicitud.Solución: Incluya un archivo en el campo file de sus datos de formulario multipart.

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

INVALID_FILE_TYPE

Estado HTTP: 400El tipo de archivo cargado no es compatible.Solución: Cargue un archivo en uno de los formatos compatibles (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

Estado HTTP: 413El archivo cargado supera el límite permitido para la suscripción autenticada: Beginner 5 GB, Starter 10 GB, Creator 20 GB, Pro 30 GB, Scale 40 GB o Enterprise 60 GB.Solución: Compruebe el límite de su plan, luego comprima el archivo, divídalo en segmentos más pequeños o actualice su plan.

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

DURATION_DETECTION_FAILED

Estado HTTP: 400No se pudo detectar la duración del archivo cargado.Solución: Asegúrese de que el archivo sea un archivo de audio o video válido y no esté dañado.

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

Errores de validación

INVALID_TARGET_LANGUAGE

Estado HTTP: 400El idioma de destino especificado no es compatible.Solución: Utilice uno de los idiomas admitidos.

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

INVALID_BOOLEAN_VALUE

Estado HTTP: 400Un parámetro booleano recibió un valor no válido.Solución: Utilice true o false (como cadenas en form-data).

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

INVALID_JSON_FORMAT

Estado HTTP: 400No se pudo analizar un parámetro JSON.Solución: Asegúrese de que la cadena JSON tenga el formato correcto.

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

INVALID_NUMBER_VALUE

Estado HTTP: 400Un campo numérico opcional de form-data no era un número válido. Envíe un valor numérico dentro del rango documentado.

LIPSYNC_VIDEO_TOO_LONG

Estado HTTP: 400Se solicitó la sincronización labial para contenido multimedia más largo que la duración admitida para la sincronización labial.Solución: Omita lipsyncPro para esta solicitud o envíe un archivo multimedia dentro del límite de sincronización labial.

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

Errores de recursos

PROJECT_NOT_FOUND

Estado HTTP: 404El proyecto especificado no existe.Solución: Verifique que el ID del proyecto sea correcto.

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

FORBIDDEN

Estado HTTP: 403No tiene permiso para acceder a este recurso.Solución: Asegúrese de estar utilizando la clave de API correcta para este proyecto.

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

Limitación de tasa

RATE_LIMIT_EXCEEDED

Estado HTTP: 429Ha excedido el límite de tasa para este endpoint.Solución: Espere antes de realizar solicitudes adicionales. Utilice retroceso exponencial.

Endpoint	Límite de tasa
`POST /v1/translate`	10 solicitudes por minuto
`POST /v1/projects`	10 solicitudes por minuto
`GET /v1/translate/{id}/status`	30 solicitudes por minuto
`GET /v1/projects/{id}`	20 solicitudes por minuto
`DELETE /v1/translate/{id}`	10 solicitudes por minuto

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

CONCURRENT_TRANSLATION_LIMIT_REACHED

Estado HTTP: 429Ya tiene el número máximo de traducciones ejecutándose en paralelo.Solución: Espere a que finalice una de sus traducciones en curso y luego vuelva a intentar la solicitud.

{
  "code": "CONCURRENT_TRANSLATION_LIMIT_REACHED",
  "message": "Concurrent translation limit reached. You can run up to 10 translations at the same time."
}

Errores de procesamiento

Estos errores pueden devolverse en el campo error al verificar el estado de la traducción:

TRANSCRIPTION_FAILED

No se pudo transcribir el audio.Posibles causas:

La calidad del audio es demasiado baja
No se detectó voz en el audio
Codificación de audio no admitida

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

TRANSLATION_FAILED

No se pudo traducir la transcripción.Posibles causas:

Par de idiomas no admitido
No se pudo procesar el contenido

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

VOICE_SYNTHESIS_FAILED

La síntesis de voz falló durante el doblaje.Posibles causas:

La clonación de voz falló
Error de generación de audio

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

LIPSYNC_FAILED

El procesamiento de sincronización labial falló.Posibles causas:

Error del proveedor de sincronización labial
Medio no válido o no compatible
La solicitud fue rechazada o cancelada

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

Errores del servidor

INTERNAL_ERROR

Estado HTTP: 500Ocurrió un error inesperado en nuestros servidores.Solución: Vuelva a intentar la solicitud. Si el problema persiste, contacte al soporte.

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

Manejo de errores

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

Descripción general

Transcripción

Traducción

Referencia

Códigos de error

Códigos de error

Formato de respuesta de error

Códigos de estado HTTP

Errores de transcripción y exportación de transcripciones

Errores de opciones de doblaje

Errores de autenticación

Errores de validación de archivos

Errores de validación

Errores de recursos

Limitación de tasa

Errores de procesamiento

Errores del servidor

Manejo de errores

​Códigos de error

​Formato de respuesta de error

​Códigos de estado HTTP

​Errores de transcripción y exportación de transcripciones

​Errores de opciones de doblaje

​Errores de autenticación

​Errores de validación de archivos

​Errores de validación

​Errores de recursos

​Limitación de tasa

​Errores de procesamiento

​Errores del servidor

​Manejo de errores

Códigos de error

Formato de respuesta de error

Códigos de estado HTTP

Errores de transcripción y exportación de transcripciones

Errores de opciones de doblaje

Errores de autenticación

Errores de validación de archivos

Errores de validación

Errores de recursos

Limitación de tasa

Errores de procesamiento

Errores del servidor

Manejo de errores