Suno API errors: 401, 402, 403, 429 and the timeout trap
Sorting the error by layer first is faster than memorising codes: either the request was refused outright, or the task was accepted and something happened later.
Two layers
Request layer: authentication, permission, balance and rate limits - these return immediately with a status code. Task layer: the task was accepted, then failed, stalled, or is still running - these are read from the task status, not the HTTP code.
The four codes you will actually see
| Code | Meaning | What to do |
|---|---|---|
| 401 | Key missing, malformed or revoked | Check Authorization: Bearer <KEY>; rotate if unsure |
| 402 | Insufficient balance | Top up; check the balance endpoint - it is free |
| 403 | Authenticated but not allowed for this call | Confirm the endpoint and the resource owner |
| 429 | Rate limited | Back off, reduce concurrency, and do not resubmit generations |
The timeout trap
Generation is asynchronous. A client timeout does not mean the order was not placed - it usually was. Query the task instead of resubmitting, and set client timeouts well above the 99th-percentile wait (a few minutes, not thirty seconds).
Failures and money
Failed tasks are refunded automatically on per-generation platforms. The two ways to create phantom charges are both self-inflicted: resubmitting after a timeout, and treating an expired download URL as a reason to regenerate.
常见问题 / FAQ
Why do I get 429 during batch runs?
Concurrency is capped. Add exponential backoff and spread submissions instead of firing them all at once.
Should I retry a failed task as-is?
No. Change a parameter or the prompt first; an identical request usually fails the same way.
How do I confirm a task actually completed?
Read the task status until it reports complete, then fetch the media URL - do not infer completion from the HTTP response of the submit call.
注册只需要邮箱，一次生成 0.6 元出 2 首，MP3 与 WAV 下载不限次。