Errors and retries

Inspect both error layers

Check the HTTP status and the JSON envelope’s code, msg and data. HTTP 200 alone does not mean the business operation succeeded. For asynchronous work, accepting a request also does not mean that the task has completed.

Result	Next step
Authentication or permission failure	Check the credential, selected Space, membership and resource access.
Invalid request	Correct fields using that endpoint’s schema; preserve their types and spelling.
Insufficient credits or plan restriction	Read quota summary and check the plan’s limits before adjusting the request.
Task failure	Inspect its terminal status and error details before using the operation’s retry path.
Rate limit	Honor `Retry-After` when present and back off.
Timeout or connection loss after submitting work	Query the existing task/project before submitting another generation.

Protect writes with idempotency

Send an Idempotency-Key of at most 128 characters for a logical write or generation request. Persist the key with the request in your application.

curl --fail-with-body "$PODCAST_API_ORIGIN/open/podcast/v1/audio/tasks" \
  -H "X-Api-Key: $PODCAST_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: episode-42-audio-v1" \
  -d '{"project_id":"PROJECT_ID"}'

Keys are scoped to the account, Space, HTTP method and URI. A completed identical request replays its recorded response. Reusing the key with different content conflicts. A pending or uncertain request is not automatically executed again. Inspect its project/task before choosing a new key.

Without a key, the operation keeps its existing Web retry semantics. Idempotency replay is request history, not current project or credit state.

Omit Idempotency-Key from repeated task-result POST requests and fresh credit checks. Reusing a completed key can replay an old polling response or estimate indefinitely.

QuickStart

Workflow guides

Account and discovery

Projects and scripts

Audio and speech

Rendering

Voices

Avatars

Media assets

Templates and visual podcasts

Errors and retries

Inspect both error layers

Protect writes with idempotency

Distinguish each task’s states

​Inspect both error layers

​Protect writes with idempotency

​Distinguish each task’s states

Inspect both error layers

Protect writes with idempotency

Distinguish each task’s states