On this page
Short answer
There are two kinds of errors. Request errors fail the HTTP call itself (wrong parameters, bad key, low balance, rate limit) and nothing is reserved. Job errors end an accepted job as failed, with an errorCode on the job, and its reserved tokens are released. The tables below list every code with the fix.
Get started
Debug a failed Seedance request
- 1
Read the code, not the message
Branch on code (request errors) or job.errorCode (job errors); messages can change, codes do not.
- 2
Check limits first
Most 400s are a duration, resolution or aspect ratio the model does not offer. GET /v1/models lists each model's limits.
- 3
Respect 429s
Wait the seconds in Retry-After before sending again.
- 4
Resend safely
After a timeout, resend with the same Idempotency-Key. After a declined prompt, change it and use a new key.
Request errors (the HTTP call fails)
| Code | Status | Meaning | Fix |
|---|---|---|---|
| invalid_api_key | 401 | The key is missing, wrong or revoked. | Send Authorization: Bearer <key>. Create a new key if it was revoked. |
| insufficient_balance | 402 | Not enough tokens for the quoted cost. | Top up under Billing. data.top_up_url links there. |
| account_not_active | 403 | The developer account is suspended. | Contact support. |
| scope_missing | 403 | The key lacks the scope this endpoint needs. | Use a key with that scope. |
| job_not_found | 404 | No job with that id for this key's account. | Check the id; jobs are private to the account. |
| character_not_found | 404 | The character id or slug doesn't exist. | List characters with GET /v1/characters. |
| upload_not_found | 404 | The upload_id doesn't exist in this workspace. | Create the upload again. |
| reference_upload_not_found | 404 | A reference upload_id doesn't exist in this workspace. | Re-upload the file and use the new upload_id. |
| video_edit_source_not_found | 404 | The source_video_upload_id doesn't exist. | Upload the clip with upload_type VIDEO. |
| upload_in_use | 409 | A queued or processing job still uses this upload. | Delete it after the job finishes. |
| character_pending | 409 | The character is still being reviewed. Nothing was reserved. | Wait retry_after seconds, then retry. |
| upload_too_large | 413 | The file is over the size limit for its type. | Images 50 MB, video 200 MB, audio 15 MB. |
| character_registration_failed | 422 | The character image did not pass review. | Register the character again with another image. |
| rate_limited | 429 | Too many requests in the window. | Wait the seconds in the Retry-After header. |
| prompt_required | 400 | No prompt (or text for speech) was sent. | Add a prompt. |
| prompt_too_long | 400 | The prompt is over the model's limit. | Shorten it; GET /v1/models lists maxPromptChars. |
| model_not_found | 400 | Unknown model alias. | Use an id from GET /v1/models. |
| duration_not_supported | 400 | The model doesn't offer that length. | Send one of the model's durations. |
| aspect_ratio_not_supported | 400 | The model doesn't offer that aspect ratio. | Send one of the model's aspect ratios. |
| resolution_not_supported | 400 | The model doesn't offer that resolution. | Send one of the model's resolutions. |
| reference_combination_not_supported | 400 | These references can't be combined, e.g. start/end frames with reference images. | Send one kind per request. |
| character_prompt_unsafe | 400 | A character prompt asks to match a real person. | Describe appearance, wardrobe, pose and style instead. |
| person_match_prompt_unsafe | 400 | A reference prompt asks to match a real person's face or likeness. | Register an owned character and describe the look instead. |
| upload_invalid | 400 | The upload request is missing a field or has a bad type. | Send file_name, mime_type, file_size and upload_type. |
| video_edit_model_not_supported | 400 | Video edits need a Seedance 2.0 family model (2.0, Fast or Mini). | Use kreator-video-pro, kreator-video-fast or kreator-video-mini. |
| video_edit_source_required | 400 | A video edit needs a source clip. | Send source_video_upload_id or video. |
| voice_required | 400 | Speech needs a voice. | Use an id from GET /v1/voices. |
| internal_error | 500 | Something failed on our side. | Retry with the same Idempotency-Key. |
| dispatch_disabled | 503 | Generation is paused for this environment. | Retry later. |
Job errors (the job ends as failed, tokens released)
| Code | Meaning | Fix |
|---|---|---|
| reference_rejected | A reference was declined (often a real person's photo). | Register the face as a character, or use another image. |
| reference_asset_pending | A new reference is still being reviewed. | Wait errorData.retry_after seconds, resubmit with the same upload_id and a new Idempotency-Key. |
| reference_asset_failed | The reference did not pass review. | Use a different file. |
| generation_rejected | The request was declined (prompt, reference or options). | Change the prompt, reference or options, then retry. |
| generation_timeout | The job did not finish in time. Reserved tokens are released. | Retry with a new Idempotency-Key. |
| generation_unavailable | The model is temporarily unavailable. | Retry later or pick another model. |
| generation_failed | The generation failed. | Retry; change the prompt or references if it repeats. |
Why was my reference rejected?
References and prompts that ask to match a real person, a celebrity or a public figure are declined. That covers photos of real people used as references and prompts that name a person to imitate. Describe appearance, wardrobe and style instead, or register a character you own with POST /v1/characters and pass its id.
Why does the output have a different aspect ratio?
With an input image or first frame, adaptive follows the image. Send an explicit aspect_ratio when the output must match a format, and check the model offers it.
Why did camera_fixed fail with an image input?
Leave camera_fixed out when you send an image or frame input, and describe the camera in the prompt instead (for example locked-off camera).
Frequently asked questions
Am I charged when a Seedance job fails?
No. A failed job's reserved tokens are released.
What does insufficient_balance mean?
Your token balance is lower than the job's quote. Top up in the console; nothing was reserved.
What should I do on a 429?
Wait the number of seconds in the Retry-After header, then send again.
Why was my prompt declined?
It asked to match a real person or broke the acceptable use policy. Change the prompt and create a new job.
