Async video API errors: save the task ID before you retry

An asynchronous video API has at least two separate outcomes: whether a task was submitted and whether generation eventually succeeded. Confusing them produces an expensive retry pattern: the application receives a slow or non-final result and sends another POST. A second creation request is another task, not a way to refresh the first task.

Build your integration around a saved task ID. Keep the original request settings, submission time, receipt, and your application’s own job reference together. Query and download are reads of that saved task. Before deciding to create another video, establish what happened to the existing submission and its reservation.

Read the response before changing the request

These are troubleshooting categories, not a claim that every provider or failure returns the same text. Read the response body and keep a received task ID even when there is an error. A missing Authorization header cannot be fixed by sending your Google browser session cookie. Use Authorization: Bearer followed by an API key created for your account.

For validation errors, compare your JSON with the documented example. Seedance 2.0 accepts four to fifteen seconds and Seedance 2.5 accepts four to thirty. Both published offerings have 480p, 720p, and 1080p tiers. Sending a display name instead of the model ID, an unsupported duration, or an assumed endpoint from another service changes the request contract.

Poll one task at a reasonable interval

queued and running are ordinary intermediate states. Query the task approximately every 15 seconds, then stop the loop when it reaches a final state or requires reconciliation. A download attempted too early returns a readiness error; it is not evidence that the video should be created again. Use succeeded as the trigger for the content request.

Keep the same key throughout the flow. A key from a different account, or another key that did not create the task, cannot be substituted to read the owned task. Store the exact ID from the receipt rather than a guessed upstream identifier. The local ID is the reference your application needs.

API_KEY='YOUR_API_KEY'
API_BASE='https://seedancelink.io'

TASK_ID='REPLACE_WITH_RESPONSE_ID'

curl --fail-with-body "$API_BASE/api/v3/contents/generations/tasks/$TASK_ID" \
  --header "Authorization: Bearer $API_KEY"

Treat needs_reconcile and lost receipts separately

A creation receipt with HTTP 202 and needs_reconcile has a local task ID. Save and query that ID. The reservation remains held for review because the submission outcome is uncertain. Do not convert this into a new automatic POST, and do not show it as if no task ever existed.

If a network interruption leaves your application with no receipt and no task ID, do not invent an ID or assume the request never reached the service. Preserve the request details and timestamp, mark the application job as unresolved, and seek help before resubmitting. This distinction lets you handle a recoverable uncertainty without knowingly risking a duplicate generation.

Use different retry rules for reads and creation

• Persist a task ID immediately after receiving it, before starting a polling loop.
• Reuse that ID for status and content reads; do not POST again to refresh progress.
• Stop downloading until succeeded, and inspect a known failure before a new generation.
• Keep private keys out of logs while retaining safe IDs, timestamps, status, and billing state.
• Escalate an unresolved submission instead of silently creating another task.

Troubleshooting questions