Errors, idempotency, and safe retries

Keep a logical operation stable

Paid create endpoints require Idempotency-Key with 8–200 characters. Generate it once, persist it with the exact request, and reuse both after a timeout or connection failure.

The same key and normalized body returns the original operation. A changed body with that key is a conflict. A request still being accepted can return a retryable in-progress conflict. Keys are retained for at least 24 hours; do not assume indefinite deduplication.

Deduplication is scoped to the account, operation, and API key identity (or OAuth client for MCP). Switching to a different API key can create a new task even with the same idempotency string. Recover a known task ID before rotating credentials during an uncertain creation.

If the create result is uncertain, first try to recover the original task. Never silently mint a new key. For a deliberate new generation or a changed request, obtain approval and use a new logical key.

Read the error envelope

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests",
    "param": null,
    "retryable": true,
    "request_id": "example-request-id",
    "details": {}
  }
}

This is an illustrative error, not a promise of identical message text. Branch on HTTP status and error.code, inspect retryable, and retain request_id for support. Do not log raw request headers, image bodies, prompts, or signed URLs.

Choose a response

Resource ownership errors can intentionally look like not-found responses. Do not probe other users' IDs.

Bound every retry loop

Respect Retry-After (seconds or HTTP date); otherwise use exponential backoff with jitter. Set a maximum number of attempts and an overall deadline. A deadline stops local waiting, not a remote task already accepted.

Retry read operations after transient transport failures. Retry an uncertain paid create only with a persisted idempotency key and unchanged body. Never retry an unkeyed upload or another non-idempotent operation blindly.

When the deadline is reached, save the known task ID and resume later. For a terminal task failure, inspect partial outputs before choosing a new export or generation.

Account limits and diagnosis

PROVIDER_CONTENT_REJECTED currently identifies a confirmed Seedance content-review rejection, not a transient error to retry unchanged. Read credits.status, credits.refunded, and credits.released from the task. credits.charged is already the net charge; do not subtract the returned credits again. A confirmed rejection before output/export refunds the original one-click workflow amount. A local timeout or an export failure is not the same condition, and a return is not approval to create another paid task.

Read current limits through GET /account; response rate-limit headers can describe the current bucket. More keys do not add account capacity. Spread polling across tasks instead of synchronizing every client in a burst.

For a support request, include the public request ID, task ID if known, timestamp, error code, and a brief description. Redact secrets and private inputs. See polling and downloads for incomplete results and the Python example for bounded retries.