Music API sync mode: wait_timeout_seconds 0-30, timed_out means poll

What sync does

Music Router jobs take mode of async, sync, subscribe or webhook. The Jobs and results page explains that sync waits up to wait_timeout_seconds for the job to reach a terminal state, and that value is clamped to 0 through 30. subscribe is an alias of sync.

A music generation can take longer than 30 seconds, so a sync call sometimes returns before the job finishes.

Reading the response

The response carries a sync object. The docs say sync.timed_out is true when the wait returned before a terminal state, and sync.capacity_exhausted is true when Sume skipped the wait because waiter capacity was not available. On async and webhook responses sync is null.

Why not resubmit

A timed-out wait is not a failed job. Submitting again creates another paid generation at $0.125. The docs are direct: not terminal means poll, do not resubmit.

• Keep the job id from the first response.
• Poll /v1/jobs/:id/status until terminal is true.
• Fetch /v1/jobs/:id/result once result_ready is true.
• If you must retry the submit, reuse the same Idempotency-Key and you get the original job.

Prefer async for music

The docs recommend async, or webhook, for anything that can outlast 30 seconds, and say sync and subscribe remain supported. For music, submit async with a webhook and use polling as a backup. That also keeps your server from holding an HTTP request open.

A polling loop that is safe

A sound loop reads the job status, sleeps a growing interval, and stops when terminal is true. Cap total time with a number you choose, such as ten minutes, and report a timeout to your own caller instead of resubmitting.

If your server restarts mid-wait, you can resume: the job id and Idempotency-Key are all you need.

Takeaway

Set wait_timeout_seconds up to 30 if you want a quick path, treat timed_out as a normal outcome, and poll. It costs nothing to wait and $0.125 to resubmit.