Status Codes & Errors
The Uspeech API follows conventional REST semantics. The HTTP status code is the source of truth for whether a request succeeded; the response body adds detail.
HTTP status codes
Section titled “HTTP status codes”| Code | Meaning |
|---|---|
200 OK | Successful read (GET) or action returning a body. |
201 Created | A new resource was created (typically a file upload). An upload’s body can include warnings. |
202 Accepted | The request was accepted and work has been queued asynchronously. |
204 No Content | Successful action with no body to return. |
400 Bad Request | The request body or query parameters are invalid. The response body describes which fields. |
401 Unauthorized | No credentials were supplied. Add the Authorization: Api-Key … header. |
403 Forbidden | Credentials are missing, malformed, revoked, the user is inactive, or the user has no access to the resource. |
404 Not Found | The resource doesn’t exist — or exists but isn’t visible to the caller. |
429 Too Many Requests | Rate limit exceeded. Retry after a short delay. |
5xx | An unexpected server error. Safe to retry idempotent reads; check status before retrying writes. |
Error response shape
Section titled “Error response shape”DRF returns errors as JSON. The exact shape depends on what failed:
Validation error (per-field):
{ "project": ["This field is required."], "file": ["No file was submitted."]}Generic error (auth, not-found, etc.):
{ "detail": "Authentication credentials were not provided."}Subscription / usage error:
{ "detail": "Free trial limit exceeded.", "reason": "free_trial_exceeded"}Always check the HTTP status first; use the body for human-readable detail.
Warnings on successful uploads
Section titled “Warnings on successful uploads”A 201 from POST /api/files/ can include a warnings list. The upload succeeded and the file is being processed, but something will affect your results. The key is only present when there is a warning.
{ "id": 1042, "status": "transcribing", "warnings": [ { "code": "call_metadata_missing", "detail": "This project analyzes calls automatically, but this call has no agent metadata, ...", "docs_url": "https://docs.uspeech.io/api/call-metadata/" } ]}| Field | Description |
|---|---|
code | Stable identifier. Match on this in your code. |
detail | Explanation for people. The wording can change. |
docs_url | The documentation page that explains the fix. |
code | When it’s set | What to do |
|---|---|---|
call_metadata_missing | The project has automatic analysis on and nothing says who the call’s agent is, so the reports will show a name guessed from the conversation. | Send the agent with the upload or in a manifest sent first. See Agent metadata with automatic analysis. |
Transcription-specific failure reasons
Section titled “Transcription-specific failure reasons”A transcription job can complete the request lifecycle (HTTP 201 on upload) and still fail asynchronously in the background. When that happens, status becomes failed and the error_reason field — returned by both GET /api/files/{id}/ and GET /api/transcripts/{id}/ — tells you why:
error_reason | When it’s set |
|---|---|
audio_too_short | The recording is shorter than 10 seconds — typically an empty, ring-only or beep-only export from a phone system. Detected right after upload, before any transcription runs, so nothing is billed. |
hallucinated_transcript | A safeguard fired: the model returned text whose timestamps extend far past the actual audio duration, which usually signals a fabricated transcript. |
private_transcription_unavailable | The project requires private transcription and the private service could not be reached. The recording was never sent to a third-party provider. |
If error_reason is empty on a failed transcript, the cause is upstream (storage, model API, etc.) — check server logs or contact support.
Authentication failures
Section titled “Authentication failures”A few common pitfalls return 401 or 403:
- Header is exactly
Authorization: Api-Key <key>(with the space afterApi-Key). - The plaintext key is
<prefix>.<secret>— both halves must be sent. - A revoked key returns
403even if it was previously valid. - An inactive user (
is_active = False) cannot use the key.
See Authentication for the full setup.