Errors and retries

Handle business errors, uncertain requests and duplicate submissions.

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 subscription benefits and adjust the request or plan.
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.

Distinguish each task’s states

Speech/audio task status 3 means success, while project status 3 means processing. Use the status and output guide; do not share one numeric state enum across all task types.