# Errores

> Identifica cada error de la API y de la transcripción. Revisa sus campos y cuándo tiene sentido reintentar.

Canonical: https://transcript1.com/es/docs/errors
Language: es
Last updated: 2026-10-19

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:

```json
{
  "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](https://transcript1.com/es/docs/sources-and-options). |
| 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](https://transcript1.com/es/docs/uploads). |
| 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](https://transcript1.com/es/docs/billing-and-limits).

## 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](https://transcript1.com/es/docs/webhooks) `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.