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.
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.
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.
