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 proyecto no está en un estado que permita la solicitud
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 - No se pudo completar la transcripción

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`	No se pudo completar la transcripción
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	`INVALID_TRANSLATED_SRT`	translatedSrt no contiene cues SRT válidos
400	`TRANSLATED_SRT_CUE_COUNT_MISMATCH`	El número de cues de translatedSrt y sourceSrt es distinto
409	`DUB_ONLY_REQUIRES_TRANSCRIPTION`	El proyecto no tiene una transcripción terminada para doblar
409	`TRANSLATION_ALREADY_IN_PROGRESS`	Ya hay un doblaje en curso para el idioma
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 seleccionada no es una voz del catálogo ni una voz personalizada guardada por la cuenta autenticada.
403	`LIPSYNC_MODE_ACCESS_DENIED`	El modo de sincronización labial premium no está disponible en el plan

Errores asíncronos de alineación SRT

Estos errores aparecen después de aceptar una solicitud de traducción o doblaje. El endpoint de estado responde con HTTP 200 y status: "failed"; su error y el webhook project.translation.failed contienen solo code y message. Los fallos guardados usan mensajes fijos de VoiceCheap; no incluyen números de cue ni índices de segmento. Los errores de solicitud síncronos, como TRANSLATED_SRT_CUE_COUNT_MISMATCH, siguen siendo HTTP 400 en la tabla anterior.

Resultado	Code	Significado
`GET` 200 / webhook	`TRANSLATED_SRT_UNMATCHED_CUES`	Un cue traducido no coincide con ningún segmento de la transcripción (se informa en el estado y en los webhooks)
`GET` 200 / webhook	`TRANSLATED_SRT_MISSING_SEGMENTS`	Un segmento de la transcripción no tiene cue traducido (se informa en el estado y en los webhooks)

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.Solución: Compruebe que su clave de API sea correcta y esté incluida en el encabezado x-api-key.

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

SUBSCRIPTION_REQUIRED

Estado HTTP: 403El acceso a la API y a MCP requiere un plan Starter o superior.Solución: Actualice a un plan Starter o superior en 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

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

Otros errores de autenticación y equipo

HTTP	Código	Descripción
401	`USER_NOT_FOUND`	No se encontró la cuenta vinculada a esta clave
403	`AMBIGUOUS_TEAM_API_KEY`	El titular de la clave pertenece a varios equipos; contacte con soporte
403	`TEAM_OWNER_NOT_FOUND`	No se encontró la cuenta del propietario del equipo vinculado

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

Errores de permisos y uso

Estado	Código	Acción
401	`API_KEY_EXPIRED`, `INVALID_MCP_TOKEN`	Usa una clave válida que no haya caducado o vuelve a conectar el asistente.
403	`INSUFFICIENT_SCOPE`	Concede el permiso necesario o elige otra credencial.
403	`SUBSCRIPTION_REQUIRED`	Usa un plan Starter o superior.
429	`INTEGRATION_MONTHLY_LIMIT_REACHED`	Espera al reinicio mensual o cambia de plan.
429	`INTEGRATION_RATE_LIMIT_REACHED`, `RATE_LIMIT_EXCEEDED`	Espera antes de volver a intentarlo y aumenta progresivamente la espera entre intentos.
429	`CONCURRENT_TRANSLATION_LIMIT_REACHED`	Espera a que termine una generación en curso.
400	`VALIDATION_ERROR`	Corrige los argumentos usando el esquema de entrada del catálogo.
404	`UNKNOWN_ACTION`	Usa un nombre de acción compatible que aparezca en el descubrimiento.

Consulta uso y límites para conocer la cuota compartida de la cuenta. Los errores no consumen llamadas mensuales. action_request_get, usage_get, projects_status y GET /v1/translate/{projectId}/status están exentas de la cuota mensual.

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

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

LIPSYNC_FAILED

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

Un problema temporal durante la sincronización labial
Medio no válido o no compatible
La solicitud fue rechazada o cancelada

{
  "code": "LIPSYNC_FAILED",
  "message": "Lip sync could not be completed. Please try again."
}

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

Descubrimiento

Cuenta

Uso y actividad

Ajustes y notificaciones

Equipo

Proyectos

Traducción y doblaje

Transcripciones y edición

Texto a voz

Voces de texto a voz

Voces de doblaje

Transcripción

Subtítulos

Imágenes

Miniaturas

Carpetas

Glosario

Webhooks

Publicación

Estado de las solicitudes

OAuth y protocolo MCP

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 asíncronos de alineación SRT

Errores de autenticación

Otros errores de autenticación y equipo

Errores de validación de archivos

Errores de validación

Errores de recursos

Errores de permisos y uso

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 asíncronos de alineación SRT

​Errores de autenticación

​Otros errores de autenticación y equipo

​Errores de validación de archivos

​Errores de validación

​Errores de recursos

​Errores de permisos y uso

​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 asíncronos de alineación SRT

Errores de autenticación

Otros errores de autenticación y equipo

Errores de validación de archivos

Errores de validación

Errores de recursos

Errores de permisos y uso

Errores de procesamiento

Errores del servidor

Manejo de errores