Skip to content

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.


CodeMeaning
200 OKSuccessful read (GET) or action returning a body.
201 CreatedA new resource was created (typically a file upload). An upload’s body can include warnings.
202 AcceptedThe request was accepted and work has been queued asynchronously.
204 No ContentSuccessful action with no body to return.
400 Bad RequestThe request body or query parameters are invalid. The response body describes which fields.
401 UnauthorizedNo credentials were supplied. Add the Authorization: Api-Key … header.
403 ForbiddenCredentials are missing, malformed, revoked, the user is inactive, or the user has no access to the resource.
404 Not FoundThe resource doesn’t exist — or exists but isn’t visible to the caller.
429 Too Many RequestsRate limit exceeded. Retry after a short delay.
5xxAn unexpected server error. Safe to retry idempotent reads; check status before retrying writes.

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.


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/"
}
]
}
FieldDescription
codeStable identifier. Match on this in your code.
detailExplanation for people. The wording can change.
docs_urlThe documentation page that explains the fix.
codeWhen it’s setWhat to do
call_metadata_missingThe 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.

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_reasonWhen it’s set
audio_too_shortThe 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_transcriptA safeguard fired: the model returned text whose timestamps extend far past the actual audio duration, which usually signals a fabricated transcript.
private_transcription_unavailableThe 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.


A few common pitfalls return 401 or 403:

  • Header is exactly Authorization: Api-Key <key> (with the space after Api-Key).
  • The plaintext key is <prefix>.<secret> — both halves must be sent.
  • A revoked key returns 403 even if it was previously valid.
  • An inactive user (is_active = False) cannot use the key.

See Authentication for the full setup.