Operate

Handle errors and manual review

Classify request errors, inspect generation failures, and stop automation when cost requires review.

On this page

HTTP errors and terminal generation failures answer different questions. An HTTP error means the attempted API action was rejected. A generation with status: failed represents accepted work that later failed.

Preserve the request ID

API error responses include type, code, message, and request_id. Log the request ID with your own operation metadata. Validation errors can also include structured details.

Retry by category, not by status code alone

Fix authentication, input, balance, and idempotency errors before retrying. Back off from rate limits and temporary availability failures. Before repeating a paid create after a timeout, read by the original response or replay the same idempotency key.

Stop on manual review

manual_review is terminal for automation. The generation's cost could not be finalized automatically, so do not cancel, retry, or create a replacement solely because time elapsed. Keep the generation ID and wait for the status and billing outcome to be resolved.

Use the error reference for stable codes and next actions.

Read the error envelope

422 Validation error

{
  "error": {
    "type": "invalid_request",
    "code": "invalid_request",
    "message": "Request validation failed.",
    "request_id": "req_0123456789abcdef",
    "details": [
      {
        "loc": [
          "body",
          "input",
          "duration_seconds"
        ],
        "msg": "Input should be less than or equal to 12",
        "type": "less_than_equal"
      }
    ]
  }
}

Choose the next action by code

authentication_errorThe bearer API key is missing, invalid, inactive, or revoked. Create or replace the organization API key.

invalid_requestThe path, body, headers, or task input failed validation. Fix the request using the current task and OpenAPI schemas.

task_not_foundThe requested task is not available. Choose a task returned by the tasks endpoint.

task_unavailableThe requested task is visible but not currently runnable. Choose a task marked as available.

model_requiredThe selected task requires a model. Choose an available model listed for that task.

model_not_allowedThe selected task does not accept a model. Remove the model field and send the task inputs directly.

model_not_foundThe requested model is not available. Choose an available model returned by the models endpoint.

model_unavailableThe requested model is visible but not currently runnable. Choose a model marked as available.

unsupported_taskThe requested model does not support the selected task. Choose a model listed for that task.

insufficient_balanceAvailable balance is below the request's current estimate. Add balance in Console or reduce the estimated request.

generation_not_foundThe generation does not exist in the key's organization. Check the generation ID and organization credential.

workflow_starter_not_foundThe Workflow Starter is not currently published. List starters and choose a returned slug.

workflow_run_not_foundThe workflow run does not exist in the key's organization. Check the public run ID and organization credential.

webhook_endpoint_not_foundThe webhook endpoint does not exist in the key's organization. List endpoints and use an endpoint ID returned for this organization.

idempotency_key_requiredThe create or retry request omitted its intent key. Send one stable Idempotency-Key for the intended write.

idempotency_conflictThe same idempotency key was reused for a different intent. Replay the original request or use a new key for new work.

starter_version_staleThe Workflow Starter contract changed. Read the starter, revalidate inputs, and estimate again.

workflow_estimate_requiredThe workflow run has not been estimated. Estimate the exact intended starter inputs before creation.

workflow_estimate_staleThe workflow estimate no longer matches current pricing. Estimate the same intended inputs again.

invalid_workflow_contractThe published starter contract cannot be executed safely. Stop and report the starter slug and request ID to support.

invalid_workflow_inputsThe inputs do not match the starter's current schema. Read the starter and correct inputs against input_schema.

unknown_workflow_costOne or more paid steps cannot be estimated. Do not create the run until every cost is known.

retry_not_allowedThe current attempt is not eligible for retry. Read the latest attempt and retry only after it fails or is cancelled.

active_retry_existsThis attempt or a later retry is still active. Monitor the active attempt before deciding on another retry.

retry_not_latestA newer attempt already exists in this retry sequence. Retry the latest attempt instead.

rate_limit_exceededRequest volume or active generation concurrency is too high. Reduce concurrency and retry with bounded exponential backoff.

invalid_media_uploadThe filename, content type, or uploaded bytes are not a supported media file. Upload a supported image, video, or audio file with matching metadata.

media_upload_timeoutThe media upload did not complete within the allowed time. Retry the upload over a stable connection with bounded exponential backoff.

media_upload_too_largeThe media file exceeds the current upload size limit. Use a smaller source file before requesting another upload.

media_storage_unavailableThe media file could not be stored temporarily. Retry the upload later with bounded exponential backoff.

service_unavailableThe media service is temporarily unavailable. Retry later with bounded exponential backoff and the same write key.

generation_failedAccepted work reached a terminal failure. Inspect final usage, then retry only when the generation is eligible.

invalid_outputCompleted work did not satisfy the task's public output contract. Treat the generation as failed and preserve its ID for support.

Inspect a failed generation

200 Failed generation

{
  "id": "gen_0123456789abcdef0123456789abcdef",
  "object": "generation",
  "status": "failed",
  "model": "seedance-2",
  "task": "video.create",
  "created_at": "2026-07-12T08:30:00Z",
  "completed_at": "2026-07-12T08:31:14Z",
  "output": null,
  "usage": {
    "amount_usd": "1.20",
    "line_items": [],
    "billing_status": "settled",
    "billing_reason": "final_cost_confirmed"
  },
  "error": {
    "code": "invalid_output",
    "message": "Completed work did not satisfy the public task contract."
  },
  "metadata": null
}

This accepted request reached a terminal failure. Inspect both the generation error and final usage before deciding whether to retry.

Stop automation for manual review

200 Generation awaiting review

{
  "id": "gen_0123456789abcdef0123456789abcdef",
  "object": "generation",
  "status": "manual_review",
  "model": "seedance-2",
  "task": "video.create",
  "created_at": "2026-07-12T08:30:00Z",
  "completed_at": "2026-07-12T08:42:00Z",
  "output": null,
  "usage": {
    "amount_usd": "1.20",
    "line_items": [],
    "billing_status": "manual_review",
    "billing_reason": "cost_requires_review"
  },
  "error": null,
  "metadata": null
}

Do not retry this generation. Preserve its ID and wait for a resolved terminal status and billing outcome.