Ir al contenido

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ódigoSignificado
200 OKLectura (GET) o acción correcta con cuerpo de respuesta.
201 CreatedSe creó un nuevo recurso (normalmente al subir un archivo). El cuerpo de una subida puede incluir avisos.
202 AcceptedLa petición se aceptó y el trabajo se ha encolado de forma asíncrona.
204 No ContentAcción correcta sin cuerpo que devolver.
400 Bad RequestEl cuerpo o los parámetros de la petición no son válidos. La respuesta indica qué campos están mal.
401 UnauthorizedNo se enviaron credenciales. Añade el encabezado Authorization: Api-Key ….
403 ForbiddenLas credenciales faltan, están mal formadas, han sido revocadas, el usuario está inactivo o no tiene acceso al recurso.
404 Not FoundEl recurso no existe — o existe pero no es visible para quien llama.
429 Too Many RequestsSe superó el límite de tasa. Reintenta tras un breve retraso.
5xxError inesperado del servidor. Es seguro reintentar lecturas idempotentes; verifica el estado antes de reintentar escrituras.

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.


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/"
}
]
}
CampoDescripción
codeIdentificador estable. Usa este valor en tu código.
detailExplicación para personas. El texto puede cambiar.
docs_urlLa página de la documentación que explica la solución.
codeCuándo apareceQué hacer
call_metadata_missingEl 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_reasonCuándo se establece
audio_too_shortLa 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_transcriptSaltó 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_unavailableEl 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.


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.