Errores | transcript1 docs

Hay dos casos distintos: la API puede rechazar tu request, o puede aceptarlo y fallar más adelante al transcribir. En este último caso, el objeto de transcripción termina con status en failed.

Cómo leer un error

Cuando /v1 rechaza un request, la respuesta tiene esta estructura:

{
  "error": {
    "code": "insufficient_minutes",
    "message": "Not enough minutes",
    "retryable": false,
    "action_url": "https://transcript1.com/dashboard/billing",
    "minutes_needed": 20,
    "minutes_remaining": 3
  }
}

Usa code para decidir qué debe hacer tu aplicación y message para mostrar la explicación al usuario. No dependas del texto de message: puede cambiar. Si retryable es true, puedes volver a enviar el mismo request más adelante.

Según el error, encontrarás otros campos junto a retryable:

Campo	Aparece en	Qué indica
`action_url`	`insufficient_minutes`	Enlace para contratar un plan o comprar minutos.
`minutes_needed`, `minutes_remaining`	`insufficient_minutes`	Minutos necesarios para el request y saldo disponible. El primero es `null` si aún no se sabe cuántos minutos necesita.
`supported_platforms`	`unsupported_platform`	Valores de plataforma admitidos: `["youtube", "x", "tiktok", "instagram", "facebook", "bluesky", "twitch", "dailymotion", "pinterest", "linkedin", "snapchat"]`.
`missing_chunks`	`upload_incomplete`	Índices de las partes del archivo que faltan por recibir.
`max_bytes`	`media_too_large`	Tamaño máximo de archivo que puedes enviar, en bytes.
`params`	`invalid_request`	Objeto que detalla el problema de cada campo al validar el cuerpo o los parámetros de la URL.

Cuando la API rechaza el request

Código HTTP	`code`	¿Reintentar?	Qué ocurrió
400, 422	`invalid_request`	No	Falta un campo o parámetro, su valor no es válido o el cuerpo no es JSON válido. También ocurre al combinar `diarize` con `source: "captions"`, o `reuse_recent` con `webhook_url`.
422	`invalid_url`	No	El enlace no se admite o no corresponde a `platform`. Usa YouTube, X, TikTok, Instagram, Facebook, Bluesky u otra plataforma de Fuentes y opciones.
422	`unsupported_platform`	No	El valor de `platform` no está entre los admitidos.
422	`unsupported_media`	No	La extensión del archivo no está admitida.
401	`unauthorized`	No	Falta la credencial, no es válida, venció o se revocó. También puede indicar que el token de subida no es válido o venció.
403	`insufficient_scope`	No	El token OAuth no tiene el permiso `transcriptions:read` o `transcriptions:write` necesario.
403	`email_not_verified`	No	Debes verificar tu correo antes de crear una transcripción.
402	`insufficient_minutes`	No	Tu saldo disponible es 0 o no alcanza para esta transcripción.
402	`no_active_plan`	No	No puedes comprar una recarga sin un plan de pago activo. Este error viene del endpoint de facturación del panel, no de los endpoints de transcripción.
404	`not_found`	No	No existe esa transcripción o es de otro equipo.
409	`upload_incomplete`	No	Faltan partes del archivo. Envíalas y vuelve a confirmar la subida.
409	`invalid_state`	No	La transcripción ya no espera una subida. No puedes enviar más partes ni confirmar que terminaste.
409	`idempotency_conflict`	No	Usaste antes el mismo `Idempotency-Key` con parámetros diferentes.
413	`media_too_large`	No	El archivo pesa más de lo permitido. Revisa Cómo subir archivos.
413	`invalid_request`	No	El cuerpo JSON supera 1 MB. Para archivos demasiado grandes, el código es `media_too_large`.
429	`rate_limited`	Sí	Superaste los requests por minuto. Espera el tiempo en segundos que indica `Retry-After`.
429	`too_many_active_jobs`	Sí	Llegaste al límite de transcripciones en curso o de subidas abiertas. Espera los segundos indicados en `Retry-After`.
500	`internal_error`	Sí	Falló algo en transcript1. Espera un momento y vuelve a intentarlo.
503	`service_unavailable`	Sí	El servicio no está disponible por el momento. Prueba de nuevo más tarde.

Si el navegador se autentica con una cookie de sesión en lugar de una credencial bearer, también se comprueba el origen. Un request desde otro sitio devuelve 403 forbidden_origin. Esta comprobación no afecta a las llamadas que usan el header Authorization.

El header Retry-After aparece en todas las respuestas 429 e indica cuántos segundos debes esperar. Puedes consultar los límites de tu plan en Facturación y límites.

Cuándo volver a intentarlo

Reenvía el request solo si retryable es true: rate_limited, too_many_active_jobs, internal_error o service_unavailable. Si hay Retry-After, respétalo. Si no, aumenta la espera entre intentos.
Si repites POST /v1/transcriptions, conserva el mismo header Idempotency-Key. Así no pagas dos veces si el primer request sí se completó.
Para los demás códigos, primero corrige lo que causó el error.

Cuando falla la transcripción

Una transcripción puede fallar después de que la API haya respondido al request de creación. Si status es failed, encontrarás el motivo en error: { "code", "message" }. Comprueba error al consultar el estado o al recibir el webhook transcription.failed.

`error.code`	Qué ocurrió	¿Qué puedes hacer?
`media_unavailable`	El video no existe o dejó de estar disponible.	No repitas el mismo envío; revisa la URL.
`media_private`	No se puede acceder porque el video es privado.	Usa una publicación pública o, en YouTube, un video público o no listado.
`login_required`	Hay que iniciar sesión en la plataforma para ver el video.	Es un fallo permanente; no se reintenta.
`no_audio`	El video no contiene una pista de audio.	Es un fallo permanente; no se reintenta.
`age_restricted`	La plataforma restringe el video por edad.	No repitas el enlace; sube el archivo.
`live_stream`	La transmisión sigue en vivo o todavía no empieza.	Espera a que termine para volver a enviarla.
`no_captions`	Pediste `captions` en `source`, pero no hay una pista de subtítulos que se pueda usar.	Cambia a `source: "auto"` o `"stt"`.
`media_too_long`	La grabación supera las 5 horas que admite voz a texto.	Divide la grabación antes de enviarla.
`unsupported_media`	No se puede leer el archivo o le falta una pista de audio.	Envía un archivo en un formato admitido.
`no_speech`	No se detectó habla.	No lo reintentes.
`unsupported_language`	El idioma de la grabación no está admitido.	Configura `language` con un código admitido o `"auto"` antes de volver a enviarla.
`insufficient_minutes`	El saldo se agotó antes de cobrar la transcripción.	Recarga minutos y vuelve a intentarlo.
`fetch_failed`	No se pudo descargar la grabación después de varios intentos.	Puedes probar de nuevo más tarde.
`transcription_failed`	La transcripción de voz a texto falló después de varios intentos.	Puedes probar de nuevo más tarde.

Si la transcripción falla o la cancelas, no pagas nada. Si ya se habían descontado minutos, vuelven a tu saldo.