Common Errors and Troubleshooting

Common error codes, causes, and handling during Seedance video generation integration.

Error Quick Reference

Error Code / Message	Cause	Handling
`401 unauthorized`	api_key invalid or not provided	Check the `Authorization: Bearer` header
`400 invalid model`	Wrong model code	Verify the code in the model list
`400 group mismatch`	Group does not match the channel family	Confirm the group the api_key belongs to
`400 invalid duration`	Duration outside the model's supported range	Refer to the duration tiers in the parameters table
`400 invalid resolution`	Unsupported resolution	Refer to the resolution tiers in the parameters table
`400 invalid ratio`	Unsupported aspect ratio	Use a supported ratio or `adaptive`
`400 asset not active`	Asset not finished processing or expired	Wait for the asset to become `active`, or re-upload
`413 Payload Too Large`	Request body too large	Use asset library references instead of embedding large files
`429 rate limited`	Too many requests	Lower the polling frequency and apply backoff retries
`500 upstream error`	Upstream channel error	Retry later, or switch groups

Confirm the model matches the group — choosing the wrong group is the most common cause of failure.
Confirm parameters are within the supported range — resolution / duration / ratio must all satisfy the model constraints simultaneously.
Confirm the asset status is active — assets in processing or failed are unavailable.
Confirm the asset matches the channel family — cross-family references always fail.
Check the request body size — when over the limit, prefer asset library references over inline embedding.

Create an asset library and upload image / video / audio assets.
Poll the asset status until it becomes active.
Call POST /v1/video/generations to submit the generation task and record the task_id.
Poll GET /v1/video/generations/{task_id} until succeeded.
Read video_url to download the video; if return_last_frame is enabled, save the last frame as well.
If the moderation result is needed, call POST /api/generation/video/moderation-result.
Clean up unused assets as needed.