Post a prompt or a brief, poll a song id.

No bearer token and no x-api-key header on the request.

Send the key as Authorization: Bearer jb_live_..., or as x-api-key. Nothing about the request changes on a retry.

The key is unknown, revoked or past its expiry. All three answer identically so the endpoint cannot be used to enumerate keys.

Check the secret was copied whole, then check the key is still live under API Keys. If it expired, issue a new one: x-key-expires-at and Sunset warn before this happens.

The key is valid but was not granted the scope this endpoint needs.

Scopes are fixed when a key is issued. Create a new key carrying the scope named in the message; there is nothing to change on the request.

No such song, lyric, persona or playlist, or one that exists but is not visible to this workspace.

Re-read the id from the endpoint that produced it. A record belonging to another workspace answers this rather than 403, so the two are indistinguishable from outside.

The workspace has spent its plan allowance for the period and has no account credit left to cover the rest.

Unlike quota_exceeded this one CAN be fixed without waiting for the period boundary: add credit or move to a larger plan, then retry the identical request. GET /usage publishes both numbers so a caller can price a render before spending it.

An Idempotency-Key was reused. Either the first request carrying it is still running, or the record it produced has since been deleted and there is nothing left to replay.

If Retry-After is present the twin is still in flight: wait that long and send the identical request again, which answers with the first one's result. Without it the first result is gone for good, and only a NEW key will render again.

The id is real and this workspace owns it, but the thing you asked for does not exist yet: audio for a song still rendering, stems for a song with no master, an extend or a cover of a track that has not landed.

Poll GET /songs/{song_id} until status is ready, then ask again. Deliberately not a 404: the id is valid, so a client that treats this as gone stops polling something that is about to succeed. Composing is 30 to 90 seconds against a cold engine, so poll every 5 seconds, not every 500ms.

The request body is over this endpoint's ceiling.

Shorten the lyric or the prompt. The bounds are published on every field, so the same bytes will never be accepted.

The request parsed but a field is missing, out of range or the wrong type.

Read error.message: it names the field and the bound it broke. Fix the payload, because a retry sends the same body.

The workspace has spent its allowance of rendered SECONDS for the billing period. Seconds, not songs: a :15 station ID and a three minute track cost the GPU wildly different amounts.

Terminal until the period rolls, and Retry-After says how long that is. GET /usage carries period_end_unix and the seconds left. NO UPGRADE SHORTENS THE WAIT: a bigger plan raises the ceiling next period, it does not refill this one. Do not retry, and do not treat this 429 like the other one: tell them apart with error.code.

Too many requests from this key. Retry-After says how long to wait.

Sleep for Retry-After seconds and retry: this one is safe to retry. Pace against RateLimit-Remaining to stay out of it.

The endpoint is implemented but this deployment has not satisfied the gate it depends on. error.message is the gate's own sentence and usually names the environment variables that would satisfy it.

Two gates are worth knowing about. Composing needs MUSIC_ENGINE_URL and MUSIC_ENGINE_TOKEN. Writing lyrics needs a language model (LLM_PROVIDER plus LLM_API_KEY), which is why POST /lyrics can be unavailable on a deployment where composing works perfectly.

Nothing about the request can fix it, so retrying is pointless until an operator acts. Render error.message rather than re-typing a variable list.

The music engine refused or could not be reached.

Retry once after a short pause. If it persists the engine itself is down and no change to the payload will help.

The engine did not answer in time. Usually a compose that landed on a GPU instance still loading the model.

Retry once, with a client timeout of 900 seconds so a legitimate 30 to 90 second cold start has room to land. Never retry in a loop. The engine runs scale-to-zero by an explicit owner decision, so the FIRST render after fifteen idle minutes is the slow one and the retry usually lands on a warm instance.

Something broke on our side. The response never carries a stack trace.

Retry once. If it persists, quote the request-id header: the detail is in our log and deliberately not in your response.