Errors

Error Format

All errors follow a consistent format:

{
  "error": {
    "message": "Human-readable error description",
    "type": "error_type",
    "code": "specific_code"
  }
}

Status	Type	Cause	Action
401	`invalid_api_key`	Missing or invalid API key	Check your API key
401	`api_key_revoked`	Key has been revoked	Create a new key
403	`insufficient_scope`	Key lacks required scope	Add required scope to key
403	`workspace_disabled`	Workspace is disabled	Contact your admin

Status	Type	Cause	Action
403	`forbidden`	Not permitted	Check workspace membership
404	`not_found`	Resource not found or not accessible	Verify the ID and workspace

Status	Type	Cause	Action
503	`provider_unavailable`	No healthy upstream session	Check connection status
503	`shutting_down`	Server shutting down	Retry shortly
502	`upstream_error`	Provider returned an error	Retry or check connection

Status	Type	Cause	Action
429	`rate_limit_exceeded`	Too many requests	Slow down request rate
429	`quota_exceeded`	Usage quota exceeded	Wait for quota reset
503	`plan_does_not_allow_audio`	Plan doesn’t include audio	Upgrade plan

Status	Type	Cause	Action
400	`audio_validation_failed`	Invalid audio file	Check format and size
400	`file_too_large`	File exceeds size limit	Use a smaller file
415	`unsupported_media_type`	MIME type not supported	Check supported formats

Status	Type	Cause	Action
400	`validation_error`	Invalid TTS request	Check voice and text
404	`job_not_found`	Job ID not found	Verify job ID
409	`job_not_ready`	Job not completed yet	Poll until completed
404	`asset_not_found`	Audio asset not found	Check job status

Status	Type	Cause	Action
503	`transcription_disabled`	Feature disabled	Contact admin
503	`transcription_provider_unavailable`	No provider	Check connections
504	`transcription_timeout`	Timeout	Try a shorter audio