> ## 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 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
**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."
}
```
**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_\"."
}
```
**Estado HTTP:** 401
La 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`.
```json theme={null}
{
"code": "INVALID_API_KEY",
"message": "The provided API key is invalid. Please check your API key and try again."
}
```
**Estado HTTP:** 403
La 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.
```json theme={null}
{
"code": "API_ACCESS_REQUIRED",
"message": "API access is required. Please request access to the API beta program."
}
```
**Estado HTTP:** 403
El acceso a la API requiere una suscripción de pago activa.
**Solución:** Actualice a un plan de pago en [voicecheap.ai](https://voicecheap.ai/pricing).
```json theme={null}
{
"code": "SUBSCRIPTION_REQUIRED",
"message": "API access requires an active paid subscription. Please upgrade your plan."
}
```
**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."
}
```
## Errores de validación de archivos
**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."
}
```
**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, ..."
}
```
**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
}
```
**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
**Estado HTTP:** 400
El idioma de destino especificado no es compatible.
**Solución:** Utilice uno de los [idiomas admitidos](/docs/es/introduction#supported-languages).
```json theme={null}
{
"code": "VALIDATION_ERROR",
"message": "Invalid target language. Allowed languages: arabic, brazilian portuguese, british english, ..."
}
```
**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\"."
}
```
**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."
}
```
**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.
**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 30 minutes. Your video is 45 minutes long."
}
```
## Errores de recursos
**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."
}
```
**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."
}
```
## Limitación de tasa
**Estado HTTP:** 429
Ha 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 |
```json theme={null}
{
"code": "RATE_LIMIT_EXCEEDED",
"message": "Too many requests. Please wait before trying again."
}
```
**Estado HTTP:** 429
Ya 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.
```json theme={null}
{
"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:
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": "Could not transcribe the audio. Please ensure the audio quality is sufficient."
}
```
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": "Failed to translate the content. Please try again."
}
```
La síntesis de voz falló durante el doblaje.
**Posibles causas:**
* La clonación de voz falló
* Error de generación de audio
```json theme={null}
{
"code": "VOICE_SYNTHESIS_FAILED",
"message": "Failed to generate the dubbed audio. Please try again."
}
```
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
```json theme={null}
{
"code": "LIPSYNC_FAILED",
"message": "Lip sync failed."
}
```
## Errores del servidor
**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}")
```