How to Call the minimax-music-3 API: curl and Python Text-to-Music Tutorial

Common Failure Modes and Debugging Tips

Async generation fails in a handful of predictable ways. Here's what to check when things go wrong.

The job never appears — submit returned 4xx

A 400 on submit almost always means a malformed payload: model missing or misspelled, prompt empty, or duration sent as a string instead of a number. A 401 means the key is missing, expired, or the header is malformed — verify the literal header string before anything else. Print the response body, not just the status code; API error bodies usually name the offending field.

Polling hangs forever

If your loop never exits, either the job is stuck or your terminal-state check is wrong. Log every status value you observe. If you see an unfamiliar state repeating, your completion predicate is too narrow. If you see nothing changing for many minutes beyond the expected duration, treat it as failed and surface the job object to your logs — and make sure you have a deadline so this can't block a worker indefinitely.

Premature polling

Polling before the job is registered or before the first status transition can return 404 or an initial "queued" state. That's normal. Handle 404 on the status call by retrying with backoff a few times rather than crashing — a transient not-found immediately after submission is a race, not an error. Only give up after several consecutive failures.

Timeouts and network stalls

If requests intermittently time out, confirm you're setting explicit timeouts on every call and not relying on library defaults. Also check whether you're polling too aggressively — a burst of status requests can trigger rate limiting, which often surfaces as timeouts or 429s rather than clean errors.

Expired result URLs

A common production failure: the job succeeded, you stored the URL, and days later the download 403s. Result URLs are short-lived. Download immediately in the same worker that observes success. If the download fails, retry a couple of times, then re-submit or re-fetch the job status — don't mark the job complete until the bytes are safely in your storage.

Duplicate jobs from retries

If your submit call times out, you may not know whether the job was accepted. Retrying can produce two songs and two bills. When retry safety matters, log the submit request with a client-side request ID and reconcile by checking recent jobs before blindly resubmitting. Better still, structure your system so submits happen once from a durable queue and the polling happens downstream.

One closing pattern worth adopting: store the job ID and status in your own database the moment you submit. Then your status endpoint, your UI progress bar, and your debugging all read from your record — not from ad-hoc polling in a request thread. That's the difference between a demo and a feature that holds up.