Saltar a la navegación

Manejo de errores

Reintentar la creación de generaciones

Para POST /v2/generate, envía una Idempotency-Key en el primer intento y reutilízala con el mismo payload en cada reintento. La guía cubre las respuestas reproducidas, los conflictos de payload, la retención y todos los errores IDEMPOTENCY_*. Una respuesta perdida o IDEMPOTENCY_OUTCOME_UNKNOWN no autoriza a usar una clave nueva ni a reintentar sin clave. Una respuesta desconocida puede incluir generationId; haz polling de ese ID cuando esté disponible.

Sin una clave, un timeout o un fallo de transporte al crear puede dejar en duda si el request fue aceptado. Confirma el resultado antes de volver a enviarlo. Los consejos generales de backoff que aparecen más abajo no hacen que repetir una creación sin clave sea seguro.

Códigos de estado HTTP

Al llamar a la API de sync. labs, puedes encontrarte con los siguientes códigos de estado HTTP. Se devuelven a nivel HTTP, antes de cualquier código de error específico de la generación.

Código de estadoNombreCausa comúnSolución
401UnauthorizedAPI key no válida o ausente. La variable de entorno SYNC_API_KEY no está definida o la clave fue revocada.Crea una clave nueva desde el Dashboard. Verifica que la clave esté incluida en el header x-api-key.
402Payment RequiredLa cuenta no puede iniciar otra generación por su estado de facturación o de plan. Las causas comunes incluyen haber agotado las generaciones del plan gratuito, no tener un plan de pago activo para un uso exclusivo de pago, una factura de uso impaga o haber superado un límite del plan.Revisa tu plan y tus facturas en la página de facturación. Las cuentas gratuitas permiten 3 generaciones de video compartidas al mes, de hasta 15 s cada una, y puedes usar las 3 con sync-3. Mejora tu plan, paga cualquier factura pendiente o espera al siguiente ciclo de facturación.
413Payload Too LargeUn archivo subido directamente a POST /v2/generate supera el límite de 5 GiB por archivo. El body incluye errorCode: generation_input_validation_failed. No se crea ninguna generación ni se retienen créditos.Usa un archivo más pequeño o pasa el archivo mediante una URL pública. Los archivos de hasta 5 GiB también deben respetar el límite de tamaño de archivo de tu plan.
429Too Many RequestsSe superó el rate limit. Consulta la página de Rate Limits para ver los límites por endpoint.Implementa backoff exponencial. Consulta la página de Rate Limits para más detalles.
500Internal Server ErrorError del lado del servidor durante el procesamiento.Reintenta tras una breve espera. El body incluye errorCode: internal_error y un requestId: incluye el requestId cuando contactes a soporte para que podamos localizar directamente el request que falló. Si persiste, revisa status.sync.so para ver el estado del servicio.
503Service UnavailableEl servicio está caído temporalmente por mantenimiento, alta carga o una caída de una dependencia de un proveedor.Reintenta con backoff exponencial, respetando el header Retry-After cuando esté presente. Revisa status.sync.so para ver incidentes en curso.
504Gateway TimeoutUn servicio de sync. labs o una dependencia de un proveedor agotó el tiempo de espera antes de completar el request.Reintenta con backoff exponencial. Si el body incluye un requestId y el timeout se sigue produciendo, inclúyelo cuando contactes a soporte.

HTML 403 o Cloudflare Access denied

Si un request a api.sync.so devuelve una página HTML que identifica a Cloudflare con HTTP 403, Access denied o el error 1010, trátalo por separado de los errores JSON de la API que se describen más abajo. Un bloqueo de Cloudflare puede ocurrir antes de la validación de la API, así que por sí solo no demuestra que tu API key, tu plan o tu media no sean válidos.

Deja de reintentar y contacta a support@sync.so con el método y el endpoint del request, el timestamp en UTC, el Ray ID de Cloudflare, la versión de tu cliente/SDK y una respuesta o captura de pantalla con los datos sensibles ocultos. Para subidas, incluye el content type y los tamaños de los archivos. No envíes API keys, headers de autorización ni URLs de media firmadas. Soporte necesita la respuesta concreta para investigar; no asumas que todos los 403 tienen la misma causa.

Un 403 de una URL de subida prefirmada a storage es un caso distinto: revisa la guía de solución de problemas de Asset Uploads para comprobar el content type y la expiración de la URL.

Códigos de error legibles por máquinas

Cada generación fallida incluye un errorCode estable y legible por máquinas junto al mensaje error legible por humanos. El errorCode aparece tanto en la respuesta de Get Generation (GET /v2/generate/{id}) como en el webhook payload que se entrega cuando termina un job.

Basa tu manejo de errores en errorCode, no en el texto de error. El mensaje error está pensado para personas y puede cambiar de redacción con el tiempo; el errorCode es un identificador estable sobre el que puedes hacer un switch en tu código con seguridad.

Una generación fallida se ve así:

{
"id": "550e8400-e29b-41d4-a716-446655440000",
"status": "FAILED",
"error": "We could not read the video file metadata. Please try a different video file.",
"errorCode": "generation_input_video_invalid"
}

Las respuestas de error de los endpoints de requests (assets, voces, TTS y rechazos de generate al momento del envío) tienen la misma forma legible por máquinas, con dos campos opcionales adicionales: field indica el campo del request que causó el fallo (por ejemplo voiceId o input[].assetId) y docsUrl enlaza a la página de documentación correspondiente. Los 500 no manejados incluyen un requestId que puedes darle a soporte, junto con errorCode: internal_error:

{
"statusCode": 422,
"errorCode": "voice_not_found",
"message": "Voice with ID \"abc\" not found. Please verify the voice ID is correct.",
"suggestion": "List valid voice ids via GET /v2/voices. Cloned voice ids are UUIDs scoped to the organization that created them.",
"field": "voiceId"
}

Consulta cualquier código en el catálogo de errores

GET /v2/errors devuelve el catálogo completo de códigos de error (los códigos de generación más los códigos de requests de la API que aparecen más abajo) como un array de objetos { code, message, suggestion }. El endpoint no requiere autenticación (no hace falta el header x-api-key), así que puedes resolver cualquier errorCode a su significado y a una solución sugerida en tiempo de ejecución.

curl https://api.sync.so/v2/errors

Una entrada típica se ve así:

{
"code": "generation_input_video_invalid",
"message": "We could not read the video file metadata. Please try a different video file.",
"suggestion": "Re-encode the video to a supported format (e.g. h264 mp4) and resubmit."
}

Lee y resuelve un código de error

Cuando una generación falla, lee su errorCode y búscalo en el catálogo que devuelve GET /v2/errors.

# 1. Fetch the failed generation
curl https://api.sync.so/v2/generate/550e8400-e29b-41d4-a716-446655440000 \
-H "x-api-key: <SYNC_API_KEY>"
# 2. Look up the returned errorCode in the catalog (no auth required)
curl https://api.sync.so/v2/errors

Errores al validar la solicitud

Algunos requests se rechazan al momento del envío: la API responde con un error en el propio request, antes de que empiece cualquier render, en lugar de aceptar el job y hacerlo fallar más tarde. Estos rechazos devuelven un estado HTTP y un errorCode legible por máquinas en el body de la respuesta, para que puedas corregir el request y volver a enviarlo sin desperdiciar una generación.

EstadoCódigo de errorCausaSolución
400invalid_generation_idEl id pasado a GET /v2/generate/{id} no es un UUID.Usa el id que devuelve POST /v2/generate.
400unsupported_generation_id_formatEl id pasado a GET /v2/generate/{id} usa un formato provider:id de otro sistema.Usa el UUID simple que devuelve POST /v2/generate.
402generation_plan_duration_exceededLa duración del output supera el límite por generación de tu plan. Tiene en cuenta sync_mode: cut_off recorta el output a la más corta de las pistas de audio y video antes de comprobar el límite.Mejora tu plan para tener un límite mayor, usa un sync_mode (como cut_off) que acorte el output o recorta la pista de entrada más larga.
404generation_not_foundEl id pasado a GET /v2/generate/{id} es un UUID válido, pero no coincide con ninguna generación de tu organización.Revisa el id y asegúrate de usar la misma API key (organización) que creó la generación.
409generation_conflictEl controller rechazó un envío interno duplicado del backend. Las creaciones públicas aceptan una Idempotency-Key opcional con alcance de organización; el ID de la generación sigue asignándolo el servidor.No reintentes a ciegas un fallo de red ambiguo; confirma el resultado del envío antes de reintentar.
409DUPLICATE_SUBMISSIONUn request con API key sin Idempotency-Key es idéntico a otro que tu organización envió en los últimos 60 segundos, y ese original no ha fallado. No se crea ninguna generación nueva.Haz polling del generationId devuelto. Para crear generaciones idénticas a propósito, envía una Idempotency-Key única con cada una. Consulta Requests without a key.
422invalid_asset_id_formatUn input[].assetId no es un UUID válido.Usa el id que devuelve POST /v2/assets o proporciona una url en su lugar.
422asset_not_foundUn input[].assetId no corresponde a ningún asset al que tu clave tenga acceso.Usa un id de asset de tu organización (GET /v2/assets); los ids de otras organizaciones no son visibles.
422generation_input_asset_type_mismatchEl tipo real de un asset no coincide con el slot de entrada en el que se pasó (por ejemplo, un asset de audio en un slot de video).Asegúrate de que el type de cada entrada coincida con el asset que pasas y de que el asset sea del tipo de media que espera ese slot.
422generation_input_too_many_visualEl request contiene más de una entrada visual; solo se permite un video o una imagen por generación.Envía exactamente una entrada de video o de imagen.
422generation_input_segments_invalidEl array segments no es válido: los segmentos se solapan, el startTime de un segmento es mayor que su endTime o dos segmentos reutilizan el mismo refId. También se devuelve para un request de lipsync: false u outputAudio no válido, por ejemplo cuando todos los segmentos definen lipsync: false o se envían varias entradas de audio sin outputAudio.Revisa tus segmentos: que no se solapen, que startTime < endTime y que cada segmento use un refId único. Para lipsync: false y outputAudio, consulta Keep segments unlipsynced.
422generation_input_dub_audio_conflictEl request incluye tanto dubParams como una entrada explícita de audio o de texto. Son mutuamente excluyentes.Envía una cosa o la otra: dubParams (para doblar) o una entrada explícita de audio/texto, pero no ambas.
422cost_estimate_unavailableEstimate Cost (POST /v2/generations/estimate) no pudo devolver un precio. No se crea ninguna generación. La validación de los campos del request devuelve 400.Comprueba que duration y el fps opcional sean números finitos y positivos. Si con entradas válidas sigue fallando, reintenta más tarde o contacta a soporte con el ID del request.
429concurrency_limit_reachedTienes demasiadas generaciones en curso para el límite de concurrencia de tu plan.Espera a que terminen las generaciones en curso o mejora tu plan para tener más concurrencia. Consulta Rate Limits.
429rate_limit_exceededSe superó tu tasa de requests por clave (por ejemplo, en requests de TTS, clonación de voz o subidas).Reduce tu tasa de requests e implementa backoff exponencial. Consulta Rate Limits.
503generation_media_probe_unavailable / generation_media_probe_timeoutUna comprobación de la media de entrada no estuvo disponible o agotó el tiempo de espera.Reintenta con backoff; verifica que el host de la media sea accesible. Incluye el ID del request cuando contactes a soporte.
503controller_unavailable / controller_dependency_errorEl servicio de generación (o una de sus dependencias) no está disponible temporalmente al momento del envío.Para una creación con clave, reintenta con la misma clave y las mismas entradas, respetando Retry-After. Para una creación sin clave, confirma la aceptación antes de volver a enviarla.
503generation_admission_pausedLos requests de generaciones nuevas están pausados temporalmente por mantenimiento. El request se rechaza antes de que empiece cualquier trabajo. Las generaciones ya aceptadas siguen procesándose y puedes seguir consultando su estado.Reintenta después del intervalo de Retry-After. Para una creación con clave, mantén la misma Idempotency-Key y las mismas entradas.
503generation_admission_unavailableLa API no puede confirmar que se estén aceptando requests de generaciones nuevas, así que rechaza el request antes de que empiece cualquier trabajo.Reintenta después del intervalo de Retry-After. Para una creación con clave, mantén la misma Idempotency-Key y las mismas entradas.
504controller_timeoutEl servicio de generación tardó demasiado en aceptar el job.Para una creación con clave, reintenta con la misma clave y las mismas entradas, respetando Retry-After. Para una creación sin clave, confirma la aceptación antes de volver a enviarla.

Un error al momento del envío devuelve errorCode en la respuesta HTTP. Los fallos de validación pueden ocurrir antes de crear la generación, pero un envío con resultado incierto puede tener ya una generación. Haz polling de generationId cuando se proporcione y sigue la guía de recuperación de idempotencia antes de reintentar.

Los errores de rate limit y de dependencias (429/503/504) también reflejan su guía de reintento en headers: Retry-After (segundos) y, para los 429 de concurrencia, X-Sync-Concurrency-Limit y X-Sync-Active-Generations.

Códigos de error de requests de la API

Además de los fallos de generación, los endpoints de assets, voces, TTS y descarga de generaciones devuelven sus propios valores estables de errorCode en las respuestas de error. Cuando corresponde, el body también incluye field (el campo del request que causó el error) y docsUrl (un enlace a la página de documentación correspondiente). Todos aparecen en el catálogo de errores (GET /v2/errors).

Assets

EstadoCódigo de errorCausaSolución
422project_not_foundEl projectId no existe en tu organización (otra organización, eliminado o mal escrito).Omite projectId o usa un id de proyecto que pertenezca a tu organización.
404asset_not_foundNo existe ningún asset con ese id en tu organización.Usa un id de asset devuelto por POST /v2/assets o GET /v2/assets. Los ids de assets de otra organización no son visibles.
403asset_forbiddenPuedes ver este asset, pero no tienes permiso para modificarlo ni eliminarlo.Solo el propietario del asset o un admin/propietario de la organización puede modificarlo.
422invalid_asset_id_formatUn assetId (incluido input[].assetId en generate) no es un UUID válido.Usa el id que devuelve POST /v2/assets o proporciona una url en su lugar.
422uploaded_file_not_foundNo se encontraron bytes del archivo en la URL de subida prefirmada.Haz PUT del archivo a la uploadUrl de POST /v2/assets/upload antes de registrar el asset.
422file_not_in_org_storageLa URL que registraste no está en el storage de sync. labs de tu organización.Sube primero el archivo con POST /v2/assets/upload y luego registra la url devuelta.
422file_size_exceeds_plan_limitEl archivo supera el tamaño máximo de tu plan.Sube un archivo más pequeño o mejora tu plan.

Voces y TTS

EstadoCódigo de errorCausaSolución
422 / 404voice_not_foundEl voiceId no corresponde a ninguna voz predefinida o clonada de tu organización. Se devuelve como 422 en POST /v2/tts y en las entradas de texto de generaciones, y como 404 en GET /v2/voices/{id} y DELETE /v2/voices/{id}.Lista los ids válidos con GET /v2/voices. Los ids de voces clonadas son UUIDs limitados a la organización que las creó.
400 / 422voice_verification_requiredLa voz seleccionada necesita verificación de ElevenLabs antes de poder usarse para síntesis. Se devuelve en POST /v2/tts y en las entradas de texto de generaciones: normalmente 422 desde la comprobación previa a la síntesis, o 400 cuando esa comprobación no estuvo disponible y la voz se rechaza durante la síntesis.Si la voz es de tu propia cuenta de ElevenLabs conectada, completa la verificación en ElevenLabs (enlazada en Settings > Integrations). Si no, elige otra voz o contacta al soporte de Sync si es una voz gestionada por Sync.
400 / 422voice_blockedElevenLabs bloqueó la voz seleccionada. Se devuelve en POST /v2/tts y en las entradas de texto de generaciones: normalmente 422 desde la comprobación previa a la síntesis, o 400 cuando esa comprobación no estuvo disponible y la voz se rechaza durante la síntesis.Elige otra voz: una voz bloqueada no se puede usar para síntesis. Si es de tu propia cuenta de ElevenLabs conectada (Settings > Integrations), contacta a ElevenLabs. Si no, para una voz gestionada por Sync, contacta al soporte de Sync.
400voice_access_deniedElevenLabs denegó el acceso a la voz seleccionada: una denegación de acceso genérica, no específicamente un estado de verificación o de bloqueo. Solo aparece durante la síntesis en POST /v2/tts y en las entradas de texto de generaciones.Elige otra voz. Si la voz es de tu propia cuenta de ElevenLabs conectada (Settings > Integrations), revisa su configuración de acceso en ElevenLabs; si no, para una voz gestionada por Sync, contacta al soporte de Sync.
422voice_sample_not_accessibleNo se encontró el asset de muestra para clonar o no es accesible.Usa un id de asset de audio o video de tu organización.
422voice_sample_type_unsupportedEl asset de muestra para clonar no es de audio ni de video.Clona a partir de un asset AUDIO o VIDEO.
422voice_sample_upload_requiredLa url de la muestra para clonar no está alojada en el storage de sync. labs.Súbela primero con POST /v2/assets/upload y luego clona a partir del assetId o la url devueltos.
422voice_sample_extraction_failedNo se pudo extraer ninguna pista de audio de la muestra de video.Comprueba que el video tenga una pista de audio y esté en un formato compatible.
400voice_sample_too_shortLa muestra es demasiado corta para clonar.Usa una muestra más larga con habla clara (idealmente de 30 segundos o más).
400voice_sample_invalidLa muestra no se pudo procesar o se agregó la misma muestra más de una vez.Usa un archivo de audio válido con habla clara y elimina cualquier muestra duplicada.
403voice_clone_limit_reachedTodos los espacios de clonación de voz de tu plan están en uso.Elimina una voz con DELETE /v2/voices/{id} o mejora tu plan.
429voice_clone_busyOtra clonación de voz compartida está reservando capacidad del proveedor.Respeta Retry-After y reintenta después del tiempo indicado.
413voice_sample_source_too_largeLa fuente de video supera el límite de 1 GiB para preparar la clonación.Recorta el video o usa una fuente más pequeña.
409voice_name_conflictYa tienes una voz con este nombre.Elige otro nombre o elimina primero la voz existente con DELETE /v2/voices/{id}.
400elevenlabs_api_key_invalidTu API key de ElevenLabs conectada (bring-your-own) no es válida o fue revocada.Vuelve a conectar una clave válida en Settings > Integrations o elimínala para volver a usar las voces compartidas.
402elevenlabs_quota_exceededSe agotó la cuota de tu propia cuenta de ElevenLabs.Revisa tu suscripción de ElevenLabs o espera a que se restablezca su cuota.
503 / 504elevenlabs_service_unavailableEl servicio de voces de ElevenLabs no está disponible temporalmente. Se devuelve como 504 para timeouts del proveedor y como 503 para otras caídas del proveedor en POST /v2/tts y en las entradas text de generaciones sin clave. Los resultados inciertos con clave usan IDEMPOTENCY_OUTCOME_UNKNOWN.Reintenta el request con backoff. Si sigue fallando, contacta a soporte con el id del request.

Descargas

GET /v2/generations/{id}/download devuelve una URL para descargar el output de una generación completada. Las generaciones inexistentes, eliminadas o de otra organización devuelven generation_not_found (404), como se explicó antes. Una API key ausente, no válida o revocada devuelve 401, y un id que no es UUID devuelve 400. Los códigos específicos de descarga son:

EstadoCódigo de errorCausaSolución
409generation_not_readyLa generación sigue pendiente o en procesamiento, así que su output todavía no está listo para descargar.Haz polling de GET /v2/generate/{id} hasta que indique COMPLETED y luego vuelve a pedir la URL de descarga.
422generation_not_downloadableLa generación falló o fue rechazada, así que no tiene output para descargar.Revisa el estado y el error de la generación con GET /v2/generate/{id}; corrige la entrada y vuelve a enviarla si hace falta.
404generation_output_unavailableLa generación no tiene ninguna referencia de output elegible o falta el archivo de output almacenado.Este endpoint no vuelve a crear outputs. Contacta a soporte si a una generación completada le falta su output.
503generation_download_unavailableNo se pudo preparar la URL de descarga.Reintenta con backoff exponencial. Si sigue fallando, contacta a soporte con el id del request.

Capacidad de subida de batches

Una subida de batch multipart puede devolver 503 con errorCode: upload_capacity_unavailable. No se creó ningún batch. Reintenta el mismo request después de los segundos indicados en Retry-After. También puedes enviar los registros como un body JSON con rows.

Recortes de audio

POST /v2/audio-trims y GET /v2/audio-trims/{id} preparan un asset de audio más corto para un video parcial. Estos códigos no están en el catálogo de errores.

EstadoCódigo de errorCausaSolución
422audio_trim_source_not_hostedEl audio está alojado fuera del storage de sync. labs.Sube el audio con POST /v2/assets/upload y luego recórtalo por assetId.
422audio_trim_source_not_allowedEl sourceUrl está en el storage de sync. labs, pero no en el de tu organización.Recorta audio que pertenezca a tu organización, o súbelo con POST /v2/assets/upload y recórtalo por assetId.
429audio_trim_rate_limitedTu organización ya tiene 4 recortes en curso o inició 60 en la última hora.Espera a que termine un recorte en curso y luego reintenta.

Un recorte que no puede decodificar o cortar el audio termina con status: failed y errorCode: audio_trim_failed en GET /v2/audio-trims/{id}. Comprueba que la fuente sea un archivo de audio legible y luego inicia un recorte nuevo con una Idempotency-Key nueva.

Reutilizar una Idempotency-Key con un body distinto devuelve 409. Una Idempotency-Key ausente, o una que no tenga entre 1 y 128 caracteres de [A-Za-z0-9._~-], devuelve 400. Una fuente de audio o un recorte que no existe o al que no tienes acceso devuelve 404. Sube primero las fuentes externas y recórtalas por assetId.

Generaciones rechazadas y fallidas

REJECTED y FAILED son estados finales. Revisa errorCode y error en la respuesta de la generación o en el webhook. REJECTED significa que el request o la cuenta necesitan una corrección antes de otro intento. FAILED significa que el procesamiento se detuvo por un error operativo. Sigue la recuperación indicada para el código devuelto y contacta a soporte si persiste.

NO_OP también es un estado final: la generación terminó, pero no se sincronizaron los labios en ningún frame, así que el output es el video de entrada sin cambios. Incluye uno de los códigos de lip sync omitido. Consulta Finished without lip sync.

Un request rechazado antes de que exista una generación devuelve su error en la respuesta HTTP. Deja de hacer polling cuando una generación llegue a cualquier estado final (COMPLETED, NO_OP, FAILED o REJECTED). Para los reintentos, sigue Idempotent requests.

¿Qué significan los códigos de error de la API?

Los códigos de abajo están agrupados por categoría, primero los más comunes.

Errores de validación de entradas

generation_unsupported_model

Mensaje: “The requested model is not supported for this operation.”

Descripción: Este error se produce cuando intentas usar un modelo que no es compatible con la operación o el endpoint de la API actual.

Solución:

  1. Consulta la documentación de modelos para ver qué modelos admite esta llamada concreta a la API.
  2. Actualiza tu request para usar un modelo compatible.
  3. Si crees que se trata de un error, contacta a nuestro equipo de soporte con los detalles de tu caso de uso.

generation_plan_duration_exceeded y generation_model_duration_exceeded

Mensaje: “The input exceeds your plan’s output-duration limit.” o “The input exceeds the selected model’s duration limit.”

Descripción: No hay un límite fijo de duración de audio para el lip sync. El output más largo que puedes generar depende de tu plan (consulta Billing), y algunos modelos tienen su propio tope, como 15 segundos para react-1. Un rechazo al momento del envío devuelve 402 generation_plan_duration_exceeded, descrito en Errores al validar la solicitud.

Solución:

  1. Recorta o divide la media para que el output entre en el límite.
  2. Si es un límite del modelo, elige un modelo con un límite mayor (consulta List Models).
  3. Si es un límite del plan, mejora tu plan para tener generaciones más largas.

Los scripts de texto a voz se validan cuando los envías: script acepta de 1 a 5,000 caracteres. Consulta Text-to-Speech.

generation_input_validation_failed

Mensaje: “Something in your input is invalid. Please check your media and settings, then try again.”

Descripción: Este error ocurre cuando los datos de entrada proporcionados no cumplen los criterios de validación necesarios para el procesamiento. Las causas comunes son una URL de entrada o un assetId que no corresponde a media descargable, o media en un formato no compatible.

Solución:

  1. Revisa tus datos de entrada para asegurarte de que cumplen todos los requisitos y especificaciones de la API.
  2. Comprueba que todos los campos obligatorios estén presentes y con el formato correcto.
  3. Verifica que los formatos de archivo, los tamaños y los demás parámetros estén dentro de los límites aceptables.
  4. Si el problema persiste, contacta a nuestro equipo de soporte con los detalles de tus datos de entrada para recibir más ayuda.

generation_input_audio_invalid

Mensaje: “We could not read the audio file metadata. Please try a different audio file.”

Descripción: Este error ocurre cuando faltan los metadatos del archivo de audio o no se pueden leer. El código equivalente para video es generation_input_video_invalid, que puedes resolver de la misma forma volviendo a codificar a MP4 H.264. Las causas típicas son archivos de audio corruptos, headers dañados o archivos de herramientas que generan metadatos no estándar.

Solución:

  1. Vuelve a codificar tu archivo de audio con una herramienta estándar como FFmpeg para asegurar que los metadatos tengan el formato correcto:
    ffmpeg -i input.wav -c:a pcm_s16le output.wav
  2. Verifica que tu archivo de audio se abra y se reproduzca correctamente en un reproductor multimedia.
  3. Comprueba que el archivo de audio no se haya corrompido durante la descarga o la transferencia.
  4. Si el problema persiste, convierte tu audio a otro formato compatible (WAV, MP3, OGG, FLAC) y vuelve a enviarlo.

generation_input_face_selection_invalid

Mensaje: “We could not use the selected speaker face for this video. Please select the face again or try auto-detect.”

Descripción: Este error ocurre cuando el rostro del hablante seleccionado manualmente no se puede usar para la generación. Es posible que el rostro seleccionado no se detecte en el video, que las coordenadas del rostro proporcionadas queden fuera del frame del video o que la selección del hablante activo no sea válida.

Solución:

  1. Vuelve a ejecutar la detección de rostros y selecciona de nuevo al hablante, asegurándote de que el rostro se vea claramente en el frame elegido.
  2. Verifica que las coordenadas o los bounding boxes proporcionados manualmente estén dentro de las dimensiones del video.
  3. Como alternativa, desactiva la selección manual del hablante para que el sistema detecte automáticamente al hablante activo y vuelve a enviar el request.

Errores de la Batch API

Los errores de validación de batches son respuestas 400 que solo incluyen un message; no tienen errorCode. Los rechazos por acceso, plan y capacidad usan los códigos que aparecen a continuación. Los dry runs requieren la misma aprobación de la organización y el mismo plan que la creación de batches.

El acceso a batch no está habilitado (batch_access_not_enabled)

Estado: 403

Descripción: Tu organización no ha sido aprobada para crear batches. El acceso está deshabilitado por defecto, incluso para las suscripciones Scale nuevas. Los dry runs requieren la misma aprobación. Los batches existentes siguen procesándose y se pueden seguir consultando cuando se retira el acceso de creación.

Solución: Contacta a support@sync.so para solicitar acceso para tu organización. Mejorar el plan no habilita el acceso automáticamente.

Batch requiere el plan Scale (plan_feature_unavailable)

Estado: 402

Descripción: La Batch API requiere la aprobación de la organización y un plan Scale o superior (Scale, Enterprise y planes de partners y programas). Los demás planes y las cuentas gratuitas no pueden crear batches. El body incluye requiredPlan y una billingUrl: requiredPlan es scale, o enterprise en los planes de créditos, porque ningún plan de créditos self-serve incluye batch.

Solución:

  1. Mejora tu plan a Scale, o contacta a ventas por Enterprise, y solicita la aprobación de tu organización para usar la Batch API.
  2. Para ejecutar unas pocas generaciones a la vez sin batch, envía requests POST /v2/generate en paralelo dentro de tu límite de concurrencia. Consulta When to use batch, and when not to.

Límite de concurrencia de batches (concurrency_limit_reached)

Estado: 429, con los headers Retry-After y X-Sync-Concurrency-Limit

Mensaje: “Batch concurrency limit reached. You have X active batches and your plan allows Y. Please wait for existing batches to complete or upgrade your plan for higher limits.”

Descripción: Ya estás ejecutando tantos batches como permite tu plan. Cada batch activo ocupa un espacio de un límite de batches igual al límite de concurrencia de tu plan. El body incluye activeBatches, concurrencyLimit y retryAfterSeconds.

Solución:

  1. Espera retryAfterSeconds o hasta que termine un batch activo.
  2. Revisa tus batches activos con GET /v2/batch.

Mensajes al validar el batch

EstadoMensajeSolución
400Input file is required / Input file cannot be emptyEnvía el JSONL en el campo input o usa un body JSON con rows.
400File size exceeds the maximum limit of 5MBEl batch supera los 5 MB tal como se envió o después de expandir sus filas de edición de diálogo. Divide los registros en varios batches.
400Number of records exceeds the maximum limit of NEnvía como máximo N registros. N es 500 por defecto, o el límite propio de tu cuenta.
400Input file must contain at least N records. Found X record(s).Un batch necesita al menos 20 registros; envía menos de 20 con POST /v2/generate.
400Invalid JSON at line X: ...Haz que cada línea sea un único objeto JSON válido.
400Duplicate request_id found at line X: ...Usa un request_id único para cada registro.
400Record at line X: request_id is required / payload is requiredAgrega el campo que falta.
400Record at line X: endpoint must be '/v2/generate'Define "endpoint": "/v2/generate".
400Record at line X: Invalid payload - ...Corrige el payload para que sea un body válido de POST /v2/generate.

Los números de línea cuentan los registros no vacíos; con un body JSON con rows, la línea N es rows[N-1].

Ejemplo: {"statusCode": 422, "errorCode": "dialogue_edit_not_found", "lineNumber": 3, "message": "Record at line 3: The dialogue edit was not found in this organization."}

Descripción: Las filas de batch que incluyen dialogueEdit (acceso anticipado) se comprueban al enviarlas, también con dry_run. Si una fila no se puede renderizar, no se crea ningún batch. La respuesta incluye el mismo errorCode que devuelve POST /v2/generate para esa vista previa, como dialogue_edit_not_found, dialogue_edit_not_completed, dialogue_edit_source_mismatch o dialogue_edit_batch_mixed_sources, más el lineNumber de la primera fila que falla. Los números de línea cuentan los registros no vacíos; con un body JSON con rows, la línea N es rows[N-1]. Los demás errores de registros del batch, como un JSON no válido, indican la línea solo en message.

Solución:

  1. Busca la fila en lineNumber y corrígela como se describe en Dialogue edit refusals.
  2. Vuelve a validar con dry_run hasta que la respuesta sea {"status": "VALIDATED"}.

Lip sync omitido

Estos códigos llegan con el estado NO_OP. La generación terminó y su outputUrl es el video de entrada sin cambios, más cualquier voz generada o audio doblado. El lip sync no se cobra. Consulta Finished without lip sync.

generation_lipsync_skipped_no_face

Mensaje: “No face was detected in the video, so nothing was lip-synced.”

Solución: Usa un video en el que el rostro del hablante se vea claramente y con un tamaño suficiente en el frame, y vuelve a enviarlo.

generation_lipsync_skipped_speaker_not_found

Mensaje: “No face was found at the selected speaker position, so nothing was lip-synced.”

Solución: Selecciona un punto en el rostro del hablante en un frame donde sea visible, o usa la detección automática del hablante, y vuelve a enviarlo.

generation_lipsync_skipped_no_active_speaker

Mensaje: “Automatic speaker detection found no one speaking, so nothing was lip-synced.”

Solución: Selecciona tú mismo al hablante con un número de frame y coordenadas, y vuelve a enviarlo. Consulta Speaker Selection.

generation_lipsync_skipped

Mensaje: “No frames were lip-synced, so the video is unchanged.”

Solución: Usa un video en el que el rostro del hablante se vea claramente y vuelve a enviarlo.

Errores del sistema y de procesamiento

generation_pipeline_failed

Mensaje: “The generation failed while processing. Please try again or contact support if this keeps happening.”

Descripción: Este error indica un fallo en uno de los pasos internos de procesamiento del pipeline de generación.

Solución:

  1. Revisa tus datos de entrada para asegurarte de que cumplen todas las especificaciones requeridas.
  2. Vuelve a enviar el request, ya que algunos errores del pipeline pueden ser temporales.
  3. Si el problema continúa, contacta a nuestro equipo de soporte con los detalles de tu request y el mensaje de error concreto para que lo investiguemos.

generation_unknown_error

Mensaje: “Something went wrong while processing this generation. Please try again.”

Descripción: La generación falló por un motivo que no tiene un código más específico.

Solución:

  1. Reintenta la generación.
  2. Si falla repetidamente, contacta a soporte con el ID de la generación.

generation_infra_storage_error

Mensaje: “An error occurred while accessing the storage on infra layer.”

Descripción: Este error indica un problema al acceder a los recursos de storage o al gestionarlos durante el proceso de generación. Puede ocurrir por problemas temporales del servicio de storage o problemas de conectividad.

Solución:

  1. Reintenta tu request tras una breve espera, ya que los errores de storage suelen ser temporales.
  2. Asegúrate de que tus archivos de entrada sean accesibles y no estén corruptos.
  3. Si el problema persiste, contacta a nuestro equipo de soporte, ya que puede indicar un problema de infraestructura más amplio.

generation_infra_resource_exhausted

Mensaje: “The infra resources are exhausted.”

Descripción: Este error ocurre cuando los recursos de infraestructura necesarios para procesar tu request no están disponibles temporalmente o están al límite de su capacidad.

Solución:

  1. Espera unos minutos y reintenta tu request, ya que la disponibilidad de recursos varía.
  2. Considera enviar tu request en horas de menor demanda, cuando hay más recursos disponibles.
  3. Si te encuentras con este error con frecuencia, contacta a nuestro equipo de soporte para hablar de tus patrones de uso y de posibles soluciones.

generation_infra_service_unavailable

Mensaje: “The infra service is unavailable.”

Descripción: Este error indica que uno o más servicios de infraestructura necesarios para el procesamiento no están disponibles temporalmente. Puede deberse a mantenimiento, problemas de conectividad o caídas del servicio.

Solución:

  1. Revisa nuestra página de estado para ver si hay problemas del servicio en curso o ventanas de mantenimiento.
  2. Reintenta tu request tras una breve espera, ya que los problemas de disponibilidad del servicio suelen ser temporales.
  3. Si el servicio sigue sin estar disponible durante un periodo prolongado, contacta a nuestro equipo de soporte para recibir actualizaciones y ayuda.

Consejos generales para solucionar problemas

  1. Revisa tu API key: asegúrate de usar la API key correcta y de que no esté revocada.
  2. Verifica el formato del request: comprueba que tu request a la API tenga el formato correcto e incluya todos los parámetros obligatorios.
  3. Revisa los rate limits: asegúrate de no haber superado los rate limits de tu API.
  4. Consulta el estado del servicio: visita nuestra página de estado para ver si hay problemas del servicio en curso.
  5. Consulta la documentación: es posible que nuestra documentación de la API se haya actualizado con información nueva o cambios.

Reporta un error poco claro o un workaround

Si un error no indicaba qué corregir, un resultado era incorrecto o necesitaste un workaround, repórtalo con Submit Feedback (POST /v2/feedback).

  • Envía un reporte por problema con un kind (confusing_error, bug, missing_capability, workaround, docs u other) y un message de hasta 4,000 caracteres que incluya el texto exacto del error.
  • Agrega el errorCode y el generationId cuando los tengas.
  • El equipo de sync. revisa los reportes a diario.
  • La llamada devuelve 202 con un id de referencia, no modifica ni reintenta ningún job y está limitada a 30 reportes por minuto.
  • El servidor MCP expone el mismo reporte como la herramienta feedback_send.
curl -X POST https://api.sync.so/v2/feedback \
-H "x-api-key: $SYNC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"kind": "confusing_error",
"severity": "major",
"message": "POST /v2/generate returned generation_input_video_inaccessible for a presigned URL that plays in a browser.",
"errorCode": "generation_input_video_inaccessible",
"generationId": "6533643b-acbb-4c4f-a5b3-5ba2e5ab6b5f"
}'

Cómo encontrar IDs de generación en Studio

Si necesitas encontrar el ID de una generación para solucionar un problema, puedes localizarlo fácilmente desde la interfaz de Studio. Los modos Studio Pro y Studio Lite siguen el mismo proceso básico:

En el modo Studio Pro: primero haz clic en el botón History de la interfaz de Studio y luego sigue los pasos de abajo.

En el modo Studio Lite: ve directamente a los pasos de abajo.

  1. Localiza tu generación: busca la miniatura de la generación cuyo ID necesitas
  2. Abre el menú: pasa el cursor sobre la miniatura de la generación y haz clic en el menú de tres puntos que aparece
  3. Copia el Job ID: selecciona copy job id en el menú desplegable
Captura de pantalla que muestra cómo copiar el job ID desde el menú de tres puntos de Studio

En el modo Agent: en el modo Agent puedes encontrar los IDs de generación de dos formas:

  1. Barra lateral de sesiones: haz clic en el menú desplegable (tres puntos) junto a cualquier sesión de la barra lateral y selecciona Copy Job ID
  2. Tarjeta de error: cuando una generación falla, haz clic en el botón Copy Job ID directamente en la tarjeta de notificación del error

Luego puedes usar este ID de generación al contactar a soporte o al hacer llamadas a la API para obtener los detalles de una generación concreta.

Si sigues teniendo problemas después de probar estos pasos, consulta la página de Troubleshooting para ver problemas comunes y sus soluciones, o contacta a nuestro equipo de soporte para recibir ayuda.

Recursos relacionados

  • Rate Limits: entiende el rate limiting de la API y cómo manejar los requests limitados
  • Webhooks: recibe notificaciones en tiempo real cuando los jobs de generación se completan o fallan
  • Inicio rápido: empieza a usar la API de sync. labs con tu primera llamada

Base de conocimiento de soporte

Preguntas frecuentes

Un error 400 significa que tu request tiene una entrada no válida. Las causas comunes incluyen una URL mal formada, un formato de media no compatible, campos obligatorios ausentes o un valor fuera del rango permitido. La media que es más larga de lo que permite tu plan se rechaza con 402 generation_plan_duration_exceeded, no con 400. Revisa el código de error concreto en el body de la respuesta para ver qué debes corregir.

Una generación en estado PENDING está esperando recursos de procesamiento. En periodos de alta demanda, los jobs pueden quedar brevemente en cola antes de empezar. Si una generación sigue en PENDING durante mucho tiempo, haz polling de su ID existente o contacta a soporte. No crees una de reemplazo solo porque sigue pendiente.

Cuando una generación termina en FAILED o REJECTED, reintenta con la misma clave y las mismas entradas: el reintento inicia una generación nueva, que se admite y se factura como un primer request. Ante un timeout o un resultado de envío desconocido, conserva la clave y las entradas originales; no inicies un reemplazo. Consulta Idempotent Requests.