Errors¶

The Icana Transcription API uses standard HTTP status codes to indicate success or failure.

HTTP Status Codes¶

Status Code	Meaning
`200`	Success
`400`	Bad Request — missing or invalid parameters
`401`	Unauthorized — invalid or missing API key
`402`	Payment Required — insufficient credit balance
`403`	Forbidden — no active account or access denied
`404`	Not Found — resource does not exist
`429`	Too Many Requests — rate limit exceeded
`500`	Internal Server Error — unexpected failure

Error Response Format¶

All error responses return a JSON object with a detail field:

{
  "detail": "Description of what went wrong"
}

Error Scenarios by Endpoint¶

`POST /api/v1/transcribe`¶

Status	Cause
`400`	Unsupported file type (allowed: `.mp3`, `.wav`, `.ogg`, `.flac`, `.m4a`, `.mp4`, `.webm`)
`401`	Invalid or missing `X-API-Key` header
`402`	Credit balance below $0.50 AUD minimum
`500`	File upload or transcription submission failed

`GET /api/v1/jobs/{job_id}`¶

Status	Cause
`401`	Invalid or missing `X-API-Key` header
`404`	Job ID not found or belongs to a different user

`GET /api/v1/jobs`¶

Status	Cause
`401`	Invalid or missing `X-API-Key` header

`GET /api/v1/usage`¶

Status	Cause
`401`	Invalid or missing `X-API-Key` header

Job Status Values¶

When polling for job results, the status field indicates the current state:

Status	Meaning
`pending`	Job is queued and waiting to be processed
`uploading`	Audio file is being uploaded to storage
`processing`	Transcription is in progress
`completed`	Job finished — `transcription` and `diarization` fields contain results
`failed`	Job failed — check `error_message` for details

Terminal statuses (polling should stop): completed, failed

Non-terminal statuses (keep polling): pending, uploading, processing

Rate Limiting¶

The API applies rate limiting to protect service availability. If you exceed the rate limit, you'll receive a 429 Too Many Requests response. Wait a moment before retrying.

Common Troubleshooting¶

Problem	Solution
`401` on every request	Check that your API key is correct and hasn't been revoked. See Authentication.
`402` when submitting	Your credit balance is too low. Top up via the dashboard (minimum $0.50 to submit).
Job stuck in `processing`	Large audio files take longer. If a job hasn't completed after 30 minutes, it may have failed silently — contact support.
`400` on file upload	Ensure the file extension is one of: `.mp3`, `.wav`, `.ogg`, `.flac`, `.m4a`, `.mp4`, `.webm`