¿La API de Transcripciones de YouTube no funciona? Lista de diagnóstico

Lista de diagnóstico

Compara tu código de error (o la forma de tu respuesta) con la tabla de abajo.

¿Bloqueado en AWS, GCP, Azure o un VPS?

Si un script funciona perfectamente en tu laptop y falla justo al desplegarlo en un servidor en la nube, casi siempre es por esto: el endpoint de subtítulos de YouTube bloquea rangos enteros de IPs de centros de datos, no solo IPs individuales abusivas. El espacio de IPs de cada gran proveedor de nube termina siendo afectado, porque miles de scripts sin relación entre sí comparten los mismos rangos de direcciones.

Could not retrieve a transcript for the video https://www.youtube.com/watch?v=...!
This is most likely caused by:
YouTube is blocking requests from your IP.

Formas realistas de evitarlo, más o menos en orden de esfuerzo:

• Enrutar peticiones por un pool de proxies residenciales o móviles - funciona a veces, pero cada vez hay más reportes de que incluso configuraciones residenciales rotativas de pago siguen fallando. No es una solución permanente.
• Rotar entre varios proveedores de nube o regiones - gana tiempo hasta que esos rangos también se marquen.
• Cachear agresivamente para no volver a pedir los mismos videos - reduce cuántas veces chocas con el bloqueo, no lo elimina.
• Usar una API alojada que ya mantiene esta infraestructura - el problema pasa de "tu proyecto" a "alguien cuyo trabajo real es mantener esto funcionando".

Ese es el vacío real que llena nuestra propia API de Transcripciones de YouTube - no una librería distinta, sino infraestructura ya construida específicamente para este problema.

¿Te sale PoTokenRequired?

Una falla más reciente: el endpoint de subtítulos de YouTube cada vez más exige un token de origen generado en tiempo de ejecución por su propio JavaScript del reproductor - no una cookie, no una verificación de reputación de IP, un valor criptográfico. Una petición HTTP simple no tiene forma de generarlo.

Mira el detalle técnico real en jdepoix/youtube-transcript-api#592 - según ese reporte, no existe una solución documentada en la librería de código abierto.

Este es exactamente el tipo de problema que una API alojada debe absorber - llama a un endpoint y recibe una transcripción o un error claro, sin tener que resolver la generación del token tú mismo.

Qué devuelve nuestra propia API en cada falla

Si ya usas nuestra API y quieres bifurcar según la falla exacta en vez de adivinar solo por el estado HTTP, cada error viene con un campo `code` estable:

curl "https://getyoutubetranscript.com/api/v1/transcript?v=dQw4w9WgXcQ" \
  -H "Authorization: Bearer sk_live_..."

# A failure looks like:
# { "success": false, "code": "TRANSCRIPT_DISABLED", "message": "Transcripts are disabled for this video." }

La referencia completa de parámetros y cada código de estado está en la documentación de la API.