Seedance API Error Codes and Troubleshooting

Understand Seedance API error responses, retry rules, rate limits, provider failures, request IDs and task-level failures.

Provider: Volcano Engine China · Last verified: 2026-07-13

Error envelope

Every explicit API error uses the same core envelope. Optional fields add parameter, retry, request-log, and documentation context.

json

{
  "error": {
    "type": "invalid_request",
    "code": "unsupported_parameter",
    "message": "frames is not supported by Seedance 2.0. Use duration instead.",
    "param": "frames",
    "retryable": false,
    "request_id": "req_01jx...",
    "docs_url": "https://seedanceapi.app/docs/parameters"
  }
}

HTTP status and error codes

HTTP	Code	Meaning	Retry
400	`invalid_json`	The request body is not valid JSON.	No
400	`invalid_request`	A type, range, URL, or field combination is invalid.	No
400	`unsupported_model`	The model name is not supported.	No
400	`unsupported_parameter`	The selected model does not support the field.	No
401	`missing_api_key`	The bearer token is missing.	No
401	`invalid_api_key`	The API key is invalid or revoked.	No
402	`insufficient_credits`	The linked user has no generation credits.	No
404	`task_not_found`	The local task is missing or belongs to another key.	No
429	`rate_limited`	The local daily API-key limit was reached.	Yes
500	`internal_error`	An unexpected local operation failed.	Yes
502	`invalid_upstream_response`	A successful provider response omitted a task ID.	Yes
502	`upstream_authentication_error`	Configured provider credentials were rejected.	No
502	`upstream_task_not_found`	A local task exists but the provider returned 404.	Yes
502	`upstream_error`	The provider error could not be mapped safely.	Limited
503	`upstream_unavailable`	The provider timed out or is temporarily unavailable.	Yes
503	`upstream_capacity_limited`	Provider queue or capacity is limited.	Yes

Invalid JSON

Malformed or empty JSON returns 400 invalid_json. A valid JSON value that is not an object returns 400 invalid_request.

Malformed requestbash

curl -X POST https://api.seedanceapi.app/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  --data-binary '{"model":'

Invalid models and parameters

Use Models and Parametersto check IDs, supported fields, ranges, and combinations. The param field identifies a field when one field caused the error.

API key errors

Missing bearer authentication returns missing_api_key. Invalid and revoked keys share invalid_api_key. This version does not add blocked-account, disabled-account, or disabled-key errors.

Insufficient credits

A task reserves its calculated local credit cost before provider submission. If the account balance is lower than the required amount, the API returns HTTP 402. Purchase credits on the Pricing page.

Task not found

Public task IDs are local vid_* IDs. The same API key must create and retrieve the task. The API intentionally uses the same 404 response for a missing task and a task owned by another key.

Rate limits

A local daily key limit returns HTTP 429 and a Retry-Afterheader for the next UTC limit window. Provider queue/capacity limits are returned separately as HTTP 503 upstream_capacity_limited.

Upstream service errors

Provider credentials are never reported as an end-user API-key error. Timeouts, network failures, and temporary service failures includeretryable=true. Use bounded exponential backoff and honorRetry-After when present.

Successful response without a task ID

A provider 2xx response without a usable task ID returns HTTP 502. The API does not create a successful local task or assume that the provider rejected the submission; the request is recorded for reconciliation.

Failed, cancelled, and expired tasks

Task status remains distinct: cancelled is not converted to failed, and expired is returned explicitly. A failed task contains a sanitized task-level error object.

json

{
  "id": "vid_01jx...",
  "object": "video.generation",
  "status": "failed",
  "error": {
    "code": "generation_failed",
    "message": "The upstream generation task failed."
  },
  "completed_at": 1783900120
}

Retry matrix

Do not retry 400, 401, or 402 without changing the request or account state.
Retry 429 after the supplied local limit interval.
Retry 502 only when retryable=true, with a small attempt limit.
Retry 503 with exponential backoff, jitter, and any Retry-After value.
Continue polling after a retryable query error; the task state is preserved.

Diagnostic checklist

Record the HTTP status, error code, and request_id.
Check the parameter and model pages for local constraints.
Inspect Dashboard request logs and the associated local task ID.
Honor retry guidance rather than retrying immediately at high concurrency.
Contact support with the request ID if a retryable failure persists.