Error handling
Check the HTTP status first, then read the response body. Even when a task query succeeds at the HTTP level, check whether the task status is failed.
HTTP status codes
The following statuses appear in the Seedance ApiPost definitions.
| Status | Meaning | Suggested action |
|---|---|---|
400 / 422 | Invalid request or parameters | Correct the input using the reported field errors |
401 | Authentication failed | Check the key and Bearer header |
403 | Access denied | Verify account and model permissions |
404 | Resource or endpoint not found | Check the path and platform task ID |
409 | Resource conflict | Check the original request status before submitting again |
413 | Request too large | Reduce the request body or media size |
429 | Rate limited | Reduce concurrency and use bounded backoff |
500 / 502 / 503 | Service error | Keep a redacted error record; retry later or contact support |
Not every endpoint returns all these statuses. Refer to the definition of each endpoint.
Two error structures
Native protocol errors contain error.code, error.message, and error.type. Parameter errors may also contain error.param.
Some platform boundary errors use code, msg, data, request_id, and time. Do not assume all errors have the same structure.
Information to provide for troubleshooting
Keep the request time, HTTP status, platform task ID, request ID (if available), and a redacted error message. Do not send API keys, Authorization headers, or complete signed download URLs.

