Seedance API Error Codes and Troubleshooting

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

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://www.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`	The generation service omitted a task ID.	Yes
502	`upstream_authentication_error`	Configured service credentials were rejected.	No
502	`upstream_task_not_found`	A local task exists but remote processing returned 404.	Yes
502	`upstream_error`	The generation error could not be mapped safely.	Limited
503	`upstream_unavailable`	Generation timed out or is temporarily unavailable.	Yes
503	`upstream_capacity_limited`	Generation capacity is temporarily 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.

bashMalformed request

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 generation 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. Generation capacity limits are returned separately as HTTP 503 upstream_capacity_limited.

Upstream service errors

Internal service 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 processing response without a usable task ID returns HTTP 502. The API does not create a successful local task or assume that generation 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.