> ## 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.

# Códigos de error

> Referencia completa de los códigos de error devueltos por la API VoiceCheap

# 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:

```json theme={null}
{
  "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:

```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"]
    }
  ]
}
```

## 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

> [accordion] MISSING\_API\_KEY
>
> **Estado HTTP:** 401
>
> No se proporcionó el encabezado `x-api-key`.
>
> **Solución:** Incluya su clave de API en el encabezado `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."
> }
> ```

> [accordion] INVALID\_API\_KEY\_FORMAT
>
> **Estado HTTP:** 401
>
> La clave de API no utiliza el prefijo `vc_` esperado.
>
> **Solución:** Compruebe que copió la clave completa desde la aplicación VoiceCheap.
>
> ```json theme={null}
> {
>   "code": "INVALID_API_KEY_FORMAT",
>   "message": "Invalid API key format. API keys must start with \"vc_\"."
> }
> ```

> [accordion] INVALID\_API\_KEY
>
> **Estado HTTP:** 401
>
> La 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`.
>
> ```json theme={null}
> {
>   "code": "INVALID_API_KEY",
>   "message": "Invalid API key. Please check your API key and try again."
> }
> ```

> [accordion] SUBSCRIPTION\_REQUIRED
>
> **Estado HTTP:** 403
>
> El 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](https://voicecheap.ai/pricing).
>
> ```json theme={null}
> {
>   "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."
> }
> ```

> [accordion] INSUFFICIENT\_CREDITS
>
> **Estado HTTP:** 403
>
> Su cuenta no tiene suficientes créditos para procesar esta solicitud.
>
> **Solución:** Compre más créditos o actualice su plan de suscripción.
>
> ```json theme={null}
> {
>   "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

> [accordion] FILE\_REQUIRED
>
> **Estado HTTP:** 400
>
> No se cargó ningún archivo con la solicitud.
>
> **Solución:** Incluya un archivo en el campo `file` de sus datos de formulario multipart.
>
> ```json theme={null}
> {
>   "code": "FILE_REQUIRED",
>   "message": "A video or audio file is required. Please upload a file with your request."
> }
> ```

> [accordion] INVALID\_FILE\_TYPE
>
> **Estado HTTP:** 400
>
> El 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).
>
> ```json theme={null}
> {
>   "code": "INVALID_FILE_TYPE",
>   "message": "Invalid file type \"application/pdf\". Supported formats: video/mp4, video/quicktime, ..."
> }
> ```

> [accordion] FILE\_TOO\_LARGE
>
> **Estado HTTP:** 413
>
> El 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.
>
> ```json theme={null}
> {
>   "code": "FILE_TOO_LARGE",
>   "message": "File size exceeds the 5GB limit for the beginner plan.",
>   "maximumFileSizeBytes": 5368709120
> }
> ```

> [accordion] DURATION\_DETECTION\_FAILED
>
> **Estado HTTP:** 400
>
> No 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.
>
> ```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."
> }
> ```

## Errores de validación

> [accordion] INVALID\_TARGET\_LANGUAGE
>
> **Estado HTTP:** 400
>
> El idioma de destino especificado no es compatible.
>
> **Solución:** Utilice uno de los [idiomas admitidos](https://api-docs.voicecheap.ai/docs/es/introduction.md#supported-languages).
>
> ```json theme={null}
> {
>   "code": "VALIDATION_ERROR",
>   "message": "Invalid target language. Allowed languages: arabic, brazilian portuguese, british english, ..."
> }
> ```

> [accordion] INVALID\_BOOLEAN\_VALUE
>
> **Estado HTTP:** 400
>
> Un parámetro booleano recibió un valor no válido.
>
> **Solución:** Utilice `true` o `false` (como cadenas en form-data).
>
> ```json theme={null}
> {
>   "code": "INVALID_BOOLEAN_VALUE",
>   "message": "Invalid boolean value for \"keepBackgroundMusic\". Expected \"true\" or \"false\", got \"yes\"."
> }
> ```

> [accordion] INVALID\_JSON\_FORMAT
>
> **Estado HTTP:** 400
>
> No se pudo analizar un parámetro JSON.
>
> **Solución:** Asegúrese de que la cadena JSON tenga el formato correcto.
>
> ```json theme={null}
> {
>   "code": "INVALID_JSON_FORMAT",
>   "message": "Invalid JSON format for \"voiceCloningSettings\". Please provide valid JSON."
> }
> ```

> [accordion] INVALID\_NUMBER\_VALUE
>
> **Estado HTTP:** 400
>
> Un campo numérico opcional de form-data no era un número válido. Envíe un valor numérico dentro del rango documentado.

> [accordion] LIPSYNC\_VIDEO\_TOO\_LONG
>
> **Estado HTTP:** 400
>
> Se 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.
>
> ```json theme={null}
> {
>   "code": "LIPSYNC_VIDEO_TOO_LONG",
>   "message": "LipSync supports up to 180 minutes. Your video is 181 minutes long."
> }
> ```

## Errores de recursos

> [accordion] PROJECT\_NOT\_FOUND
>
> **Estado HTTP:** 404
>
> El proyecto especificado no existe.
>
> **Solución:** Verifique que el ID del proyecto sea correcto.
>
> ```json theme={null}
> {
>   "code": "PROJECT_NOT_FOUND",
>   "message": "Project with ID 'abc123' not found."
> }
> ```

> [accordion] FORBIDDEN
>
> **Estado HTTP:** 403
>
> No tiene permiso para acceder a este recurso.
>
> **Solución:** Asegúrese de estar utilizando la clave de API correcta para este proyecto.
>
> ```json theme={null}
> {
>   "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](https://api-docs.voicecheap.ai/docs/es/api-reference/limits.md) 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:

> [accordion] 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
>
> ```json theme={null}
> {
>   "code": "TRANSCRIPTION_FAILED",
>   "message": "The transcription could not be completed. Please try again."
> }
> ```

> [accordion] TRANSLATION\_FAILED
>
> No se pudo traducir la transcripción.
>
> **Posibles causas:**
>
> * Par de idiomas no admitido
> * No se pudo procesar el contenido
>
> ```json theme={null}
> {
>   "code": "TRANSLATION_FAILED",
>   "message": "The translation could not be completed. Please try again."
> }
> ```

> [accordion] 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
>
> ```json theme={null}
> {
>   "code": "LIPSYNC_FAILED",
>   "message": "Lip sync could not be completed. Please try again."
> }
> ```

## Errores del servidor

> [accordion] INTERNAL\_ERROR
>
> **Estado HTTP:** 500
>
> Ocurrió un error inesperado en nuestros servidores.
>
> **Solución:** Vuelva a intentar la solicitud. Si el problema persiste, contacte al soporte.
>
> ```json theme={null}
> {
>   "code": "INTERNAL_ERROR",
>   "message": "An unexpected error occurred. Please try again later."
> }
> ```

## Manejo de errores

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.