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
Sección titulada «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). El cuerpo de una subida puede incluir avisos. |
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
Sección titulada «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.
Avisos en subidas correctas
Sección titulada «Avisos en subidas correctas»Un 201 de POST /api/files/ puede incluir una lista warnings. La subida se realizó y el archivo se está procesando, pero algo afectará a tus resultados. La clave solo aparece cuando hay un aviso.
{ "id": 1042, "status": "transcribing", "warnings": [ { "code": "call_metadata_missing", "detail": "Este proyecto analiza las llamadas automáticamente, pero esta llamada no tiene metadatos del agente, ...", "docs_url": "https://docs.uspeech.io/es/api/call-metadata/" } ]}| Campo | Descripción |
|---|---|
code | Identificador estable. Usa este valor en tu código. |
detail | Explicación para personas. El texto puede cambiar. |
docs_url | La página de la documentación que explica la solución. |
code | Cuándo aparece | Qué hacer |
|---|---|---|
call_metadata_missing | El proyecto tiene el análisis automático activado y nada indica quién es el agente de la llamada, así que los informes mostrarán un nombre deducido de la conversación. | Envía el agente con la subida o en un manifiesto enviado antes. Consulta Metadatos del agente con análisis automático. |
Motivos de fallo específicos de transcripción
Sección titulada «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 pasa a failed y el campo error_reason — devuelto tanto por GET /api/files/{id}/ como por GET /api/transcripts/{id}/ — indica el motivo:
error_reason | Cuándo se establece |
|---|---|
audio_too_short | La grabación dura menos de 10 segundos — normalmente una exportación vacía, solo con tono de llamada o solo con un pitido, generada por el sistema telefónico. Se detecta justo después de la subida, antes de transcribir nada, así que no se cobra. |
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. |
private_transcription_unavailable | El proyecto requiere transcripción privada y no se pudo contactar con el servicio privado. La grabación nunca se envió a un proveedor externo. |
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.
Fallos de autenticación
Sección titulada «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 deApi-Key). - La clave en texto plano es
<prefix>.<secret>— debes enviar ambas partes. - Una clave revocada devuelve
403aunque antes fuera válida. - Un usuario inactivo (
is_active = False) no puede usar la clave.
Consulta Autenticación para la configuración completa.