Errores

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:

Cuando la API rechaza el request

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, too_many_live_sessions, live_capacity, internal_error, service_unavailable, y topup_needs_user con reason pending o in_progress. Si hay Retry-After, respétalo. Si no, aumenta la espera entre intentos.
• Si repites POST /v1/transcriptions o POST /v1/topups, 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.

Transcripción en vivo

POST /v1/live/sessions y los demás endpoints en vivo usan el mismo formato de error. A ellos también se aplican invalid_request, unsupported_language, insufficient_minutes y email_not_verified, junto con los códigos en vivo de la tabla anterior. Crear una sesión no es idempotente, así que reintentar tras too_many_live_sessions o live_capacity crea una sesión nueva.

Una vez que la sesión existe, los problemas llegan por el WebSocket como eventos error y códigos de cierre, no como errores HTTP. Consulta todos los eventos en Transcripción en vivo.

Una sesión en vivo que termina por un motivo como balance_exhausted o idle_timeout no es un error: envía session.ended con el motivo del final y se guarda. Consulta Motivos de finalización.

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. Si una traducción falla, se envía el webhook transcription.translation.failed y la transcripción nunca falla por ello.

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