> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt. # Errores ## Errores de la API ElevenLabs utiliza códigos de estado HTTP estándar para indicar si una solicitud se ha realizado correctamente o ha fallado. Además, todas las solicitudes a la API devuelven un objeto JSON con una propiedad `detail` que contiene información sobre el error. En general, un código de estado HTTP `200` indica que la solicitud se ha realizado correctamente. Un código `4xx` indica un problema con la solicitud, como un parámetro no válido o la falta de un campo obligatorio. Un código de estado HTTP `500` indica un problema con los servidores de ElevenLabs, algo que debería ocurrir rara vez. ### Propiedades de los errores | Propiedad | Descripción | | ------------ | ---------------------------------------------------------------------------------------------------------------------- | | `type` | El tipo de error que se ha producido. Consulta la tabla siguiente para ver los posibles valores. | | `code` | El código del error. Es más específico que el tipo y puede utilizarse para determinar la causa del error. | | `message` | El mensaje del error. Proporciona más detalles sobre el error. | | `status` | El estado del error. Es un campo heredado que ya no se utiliza; usa en su lugar la propiedad `code`. | | `request_id` | El ID de solicitud del error. Es un identificador único de la solicitud que puede utilizarse para solucionar el error. | | `param` | El parámetro que ha causado el error. En caso de error de validación, indicará el parámetro que no es válido. | ### Ejemplo de respuesta de error Esta es la respuesta de una solicitud a la API que ha utilizado un ID de modelo incorrecto: ```json { "detail": { "type": "validation_error", "code": "invalid_parameters", "message": "The 'keyterms' parameter is only supported with the 'scribe_v2' model. You specified 'scribe_v1'.", "status": "invalid_parameters", "request_id": "3c807fc4c3a1705f9638ecc764a91c01", "param": "keyterms" } } ``` Con las propiedades del error, podemos ver que se trata de un error de validación y que el código es `invalid_parameters`. El mensaje ofrece más detalles sobre el error y `request_id` es un identificador único de la solicitud que puede utilizarse para solucionar el error. La propiedad `param` indica el parámetro que ha causado el error. ### Gestión de errores en los SDK Los SDK de ElevenLabs proporcionan clases de error tipadas que te dan acceso a los detalles del error. ```python from elevenlabs import ElevenLabs from elevenlabs.core import ApiError elevenlabs = ElevenLabs() try: audio = elevenlabs.text_to_speech.convert( voice_id="invalid-voice-id", model_id="eleven_v4", text="Hello, world!", ) except ApiError as e: print(f"Status code: {e.status_code}") # Access the error body if e.body and "detail" in e.body: detail = e.body["detail"] print(f"Error type: {detail.get('type')}") print(f"Error code: {detail.get('code')}") print(f"Message: {detail.get('message')}") print(f"Request ID: {detail.get('request_id')}") # Handle specific error types if detail.get("type") == "rate_limit_error": print("Rate limited - implement exponential backoff") elif detail.get("type") == "authentication_error": print("Check your API key") ``` ```typescript import { ElevenLabsClient, ElevenLabsError } from "@elevenlabs/elevenlabs-js"; const elevenlabs = new ElevenLabsClient(); try { const audio = await elevenlabs.textToSpeech.convert("invalid-voice-id", { text: "Hello, world!", modelId: "eleven_v4", }); } catch (error) { if (error instanceof ElevenLabsError) { console.log(`Status code: ${error.statusCode}`); // Access the error body const detail = (error.body as any)?.detail; if (detail) { console.log(`Error type: ${detail.type}`); console.log(`Error code: ${detail.code}`); console.log(`Message: ${detail.message}`); console.log(`Request ID: ${detail.request_id}`); // Handle specific error types if (detail.type === "rate_limit_error") { console.log("Rate limited - implement exponential backoff"); } else if (detail.type === "authentication_error") { console.log("Check your API key"); } } } } ``` Si no puedes resolver el error, envía un correo a Soporte a [support@elevenlabs.io](mailto:support@elevenlabs.io) con el `request_id` de la respuesta de error, el mensaje de error completo y los pasos para reproducir el problema. #### Límite de solicitudes y concurrencia Si recibes un código de estado HTTP 429, significa que has realizado demasiadas solicitudes en poco tiempo y has superado el límite de solicitudes de la ruta de API, o que has superado el límite de concurrencia de la ruta de API. El `code` de error será `rate_limit_exceeded` o `concurrent_limit_exceeded`, respectivamente. En caso de límite de solicitudes, debes implementar un retroceso exponencial en tu código cuando recibas un error 429. Esto implica añadir una espera antes de volver a intentar la solicitud. En caso de concurrencia, debes esperar a que terminen las solicitudes actuales antes de hacer otras nuevas. Consulta la sección [Concurrencia y prioridad](/docs/es/overview/models#concurrency-and-priority) para obtener más información. ### Tipos de error Un error incluye una propiedad `type` que indica el tipo de error que se ha producido. Consulta la tabla siguiente para ver los posibles valores. | Tipo | Descripción | Código de estado HTTP | | ---------------------- | ------------------------------------------------------------------------- | --------------------- | | `validation_error` | La solicitud contiene valores de parámetros no válidos. | 400 | | `invalid_request` | La estructura de la solicitud no es válida o faltan campos obligatorios. | 400 | | `authentication_error` | Error de autenticación: clave o token de API no válido o ausente. | 401 | | `payment_required` | El usuario no tiene créditos suficientes o se requiere un pago. | 402 | | `authorization_error` | El usuario autenticado no tiene los permisos necesarios para esta acción. | 403 | | `not_found` | No se ha encontrado el recurso solicitado. | 404 | | `conflict` | La solicitud entra en conflicto con el estado actual del recurso. | 409 | | `rate_limit_error` | Demasiadas solicitudes; inténtalo de nuevo más tarde. | 429 | | `internal_error` | Se ha producido un error inesperado del servidor. | 500 | | `service_unavailable` | El servicio no está disponible temporalmente; debería ocurrir rara vez. | 503 | ### Códigos de error
Código Tipo Descripción
`voice_not_found` `not_found` El ID de voz especificado no existe. Comprueba el ID de voz e inténtalo de nuevo.
`sample_not_found` `not_found` No se ha encontrado la muestra de voz especificada.
`voice_collection_not_found` `not_found` La colección de voces especificada no existe.
`user_not_found` `not_found` No se ha encontrado el usuario especificado.
`auth_account_not_found` `not_found` No se ha encontrado la cuenta de autenticación.
`workspace_not_found` `not_found` El espacio de trabajo especificado no existe.
`project_not_found` `not_found` No se ha encontrado el proyecto especificado.
`history_item_not_found` `not_found` El elemento del historial especificado no existe.
`collection_not_found` `not_found` No se ha encontrado la colección especificada.
`document_not_found` `not_found` El documento especificado no existe.
`file_not_found` `not_found` No se ha encontrado el archivo especificado.
`conversation_not_found` `not_found` La conversación especificada no existe.
`agent_not_found` `not_found` No se ha encontrado el agente especificado.
`dubbing_not_found` `not_found` El proyecto de doblaje especificado no existe.
`song_not_found` `not_found` No se ha encontrado la canción especificada.
`read_not_found` `not_found` No se ha encontrado la lectura especificada.
`pronunciation_dictionary_not_found` `not_found` El diccionario de pronunciación especificado no existe.
`knowledge_base_not_found` `not_found` No se ha encontrado la base de conocimientos especificada.
`phone_number_not_found` `not_found` El número de teléfono especificado no existe.
`tool_not_found` `not_found` No se ha encontrado la herramienta especificada.
`snapshot_not_found` `not_found` La instantánea especificada no existe.
`task_not_found` `not_found` No se ha encontrado la tarea especificada.
`model_not_found` `not_found` El modelo especificado no existe.
`transcript_not_found` `not_found` No se ha encontrado la transcripción especificada.
`keywords_list_not_found` `not_found` No se ha encontrado la lista de palabras clave especificada.
`category_not_found` `not_found` No se ha encontrado la categoría especificada.
`text_too_long` `validation_error` El texto proporcionado supera la longitud máxima permitida.
`text_too_short` `validation_error` El texto proporcionado es más corto que la longitud mínima requerida.
`invalid_text` `validation_error` El texto proporcionado contiene caracteres o formato no válidos.
`empty_text` `validation_error` El campo de texto no puede estar vacío.
`invalid_parameters` `validation_error` Uno o más parámetros de la solicitud no son válidos. Consulta la propiedad `param` para ver el parámetro no válido.
`missing_required_field` `validation_error` Falta un campo obligatorio en la solicitud. Consulta la propiedad `param` para ver el campo que falta.
`invalid_voice_settings` `validation_error` La configuración de voz contiene valores no válidos. Consulta la propiedad `param` para ver la configuración de voz no válida.
`invalid_voice_id` `validation_error` El formato del ID de voz no es válido.
`unsupported_model` `validation_error` El modelo especificado no es compatible con esta operación.
`invalid_audio` `validation_error` El audio proporcionado no es válido o está dañado.
`invalid_audio_format` `validation_error` El formato de audio especificado no es compatible.
`invalid_output_format` `validation_error` El formato de salida solicitado no es compatible.
`audio_too_long` `validation_error` El audio supera la duración máxima permitida.
`audio_too_short` `validation_error` El audio es más corto que la duración mínima requerida.
`invalid_file_type` `validation_error` El tipo de archivo no es compatible.
`invalid_page_size` `validation_error` El parámetro de tamaño de página está fuera del intervalo permitido.
`invalid_cursor` `validation_error` El cursor de paginación no es válido o ha caducado.
`bad_request` `invalid_request` El servidor no ha podido entender la solicitud.
`malformed_json` `invalid_request` El cuerpo de la solicitud contiene JSON no válido.
`invalid_content_type` `invalid_request` La cabecera Content-Type falta o no es válida.
`request_too_large` `invalid_request` El cuerpo de la solicitud supera el tamaño máximo permitido.
`invalid_api_key` `authentication_error` La clave de API proporcionada no es válida.
`missing_api_key` `authentication_error` No se ha proporcionado ninguna clave de API en la solicitud.
`invalid_authorization_header` `authentication_error` El formato de la cabecera Authorization no es válido.
`unauthorized` `authentication_error` Se requiere autenticación para acceder a este recurso.
`sign_in_required` `authentication_error` Debes iniciar sesión para realizar esta acción.
`forbidden` `authorization_error` El acceso a este recurso está prohibido.
`insufficient_permissions` `authorization_error` No tienes los permisos necesarios para esta acción.
`workspace_access_denied` `authorization_error` No tienes acceso a este espacio de trabajo.
`feature_not_available` `authorization_error` Esta función no está disponible en tu plan actual.
`subscription_required` `authorization_error` Se requiere una suscripción de pago para acceder a esta función.
`voice_access_denied` `authorization_error` No tienes acceso a esta voz.
`model_access_denied` `authorization_error` No tienes acceso a este modelo.
`conflict` `conflict` Se ha producido un conflicto.
`resource_already_exists` `conflict` Ya existe un recurso con el mismo identificador.
`voice_already_exists` `conflict` Ya existe una voz con este nombre.
`already_running` `conflict` La operación ya está en ejecución.
`already_processing` `conflict` El recurso ya se está procesando.
`concurrent_modification` `conflict` Otra solicitud ha modificado el recurso. Vuelve a intentarlo con la versión más reciente.
`slug_already_exists` `conflict` Ya existe un recurso con este slug.
`rate_limit_exceeded` `rate_limit_error` Demasiadas solicitudes. Espera antes de volver a intentarlo.
`concurrent_limit_exceeded` `rate_limit_error` Se ha superado el número máximo de solicitudes simultáneas. Los niveles de suscripción superiores tienen un límite de concurrencia más alto.
`system_busy` `rate_limit_error` El sistema está ocupado actualmente. Inténtalo de nuevo más tarde.
`insufficient_credits` `payment_required` Tu cuenta no tiene suficientes créditos para esta operación.
`internal_error` `internal_error` Se ha producido un error inesperado. Ponte en contacto con Soporte si el problema persiste.
`service_unavailable` `service_unavailable` El servicio no está disponible temporalmente. Inténtalo de nuevo más tarde.
`maintenance` `service_unavailable` El servicio está en mantenimiento programado.