Códigos de estado y errores

⚠️ Códigos de estado y errores

La API de Uspeech sigue la semántica REST convencional. El código de estado HTTP es la fuente de verdad sobre si una petición tuvo éxito; el cuerpo de la respuesta añade los detalles.

Códigos de estado HTTP

Código	Significado
`200 OK`	Lectura (`GET`) o acción correcta con cuerpo de respuesta.
`201 Created`	Se creó un nuevo recurso (normalmente al subir un archivo).
`202 Accepted`	La petición se aceptó y el trabajo se ha encolado de forma asíncrona.
`204 No Content`	Acción correcta sin cuerpo que devolver.
`400 Bad Request`	El cuerpo o los parámetros de la petición no son válidos. La respuesta indica qué campos están mal.
`401 Unauthorized`	No se enviaron credenciales. Añade el encabezado `Authorization: Api-Key …`.
`403 Forbidden`	Las credenciales faltan, están mal formadas, han sido revocadas, el usuario está inactivo o no tiene acceso al recurso.
`404 Not Found`	El recurso no existe — o existe pero no es visible para quien llama.
`429 Too Many Requests`	Se superó el límite de tasa. Reintenta tras un breve retraso.
`5xx`	Error inesperado del servidor. Es seguro reintentar lecturas idempotentes; verifica el estado antes de reintentar escrituras.

Estructura de la respuesta de error

DRF devuelve los errores como JSON. La forma exacta depende del fallo:

Error de validación (por campo):

{
  "project": ["This field is required."],
  "file": ["No file was submitted."]
}

Error genérico (auth, no encontrado, etc.):

{
  "detail": "Authentication credentials were not provided."
}

Error de suscripción / uso:

{
  "detail": "Free trial limit exceeded.",
  "reason": "free_trial_exceeded"
}

Comprueba siempre primero el código HTTP; usa el cuerpo para los detalles legibles.

Motivos de fallo específicos de transcripción

Un trabajo de transcripción puede completar el ciclo de la petición (HTTP 201 en la subida) y aun así fallar de forma asíncrona en segundo plano. Cuando eso ocurre, el status del registro de transcripción pasa a failed y el campo error_reason indica el motivo:

`error_reason`	Cuándo se establece
`audio_too_short`	El audio está por debajo de la duración mínima necesaria para transcribir — normalmente grabaciones vacías o que solo contienen un pitido.
`hallucinated_transcript`	Saltó una salvaguarda: el modelo devolvió texto cuyas marcas de tiempo se extienden mucho más allá de la duración real del audio, lo que suele indicar una transcripción fabricada.

Si error_reason está vacío en una transcripción fallida, la causa está más arriba (almacenamiento, API del modelo, etc.) — revisa los logs del servidor o contacta con soporte.

💡 Consejo: al consultar GET /api/files/{id}/, considera failed como estado terminal. No reintentes a ciegas — para audio_too_short el archivo no tiene nada que transcribir; para hallucinated_transcript, volver a subir el mismo audio probablemente dará el mismo resultado.

Fallos de autenticación

Algunos errores comunes devuelven 401 o 403:

El encabezado debe ser exactamente Authorization: Api-Key <key> (con el espacio después de Api-Key).
La clave en texto plano es <prefix>.<secret> — debes enviar ambas partes.
Una clave revocada devuelve 403 aunque antes fuera válida.
Un usuario inactivo (is_active = False) no puede usar la clave.

Consulta Autenticación para la configuración completa.