Errors

Error response structure

OpenAPI endpoints return a structured error object when the request cannot be accepted:

{
  "error": {
    "code": "not_found",
    "type": "resource_error",
    "message": "Generation not found",
    "retryable": false,
    "details": {}
  }
}

If the error happens after a generation has been created, the same error object is embedded in the generation resource returned by polling or webhook delivery:

{
  "id": "gen_abc123",
  "status": "failed",
  "model": "bytedance/seedance/v2/image-to-video",
  "output": [],
  "error": {
    "code": "generation_failed",
    "type": "provider_error",
    "message": "Generation failed due to a temporary issue. Please try again later.",
    "retryable": true,
    "details": {
      "trace_ref": "1DEC",
      "request_id": "454556e0e86cd4ee60a7cf9825571dec",
      "category": "temporary",
      "field_errors": [
        {
          "field": ["reference_assets", 0, "url"],
          "type": "reference_image_upload_failed",
          "message": "Reference image 1 could not be uploaded for media validation.",
          "constraint": {
            "stage": "upload",
            "index": 0
          }
        }
      ]
    }
  }
}

For asynchronous jobs, GET /open/v1/generations/{id} and generation.failed webhooks use the same generation projection. The lightweight GET /open/v1/generations/{id}/status endpoint only returns status progress fields and does not include full error details.

Error object

Message levels

error.message is a short, stable summary for alerts, logs, and default UI copy. It should explain the overall failure without embedding long provider output, raw payloads, or per-field diagnostics.

Use error.details.field_errors[].message for scoped diagnostics tied to a specific field, asset, or output. These messages can include the concrete provider-safe reason, such as a raw text output when an image model returned text instead of an image.

{
  "error": {
    "code": "no_output",
    "message": "The model did not produce an image for this prompt. Try rephrasing the prompt.",
    "details": {
      "field_errors": [
        {
          "field": ["output"],
          "type": "model_text_output_without_image",
          "message": "Raw model output: \"I cannot generate that image.\"",
          "constraint": {
            "rawOutput": "I cannot generate that image."
          }
        }
      ]
    }
  }
}

Details object

When the underlying generation queue returns a public error, OpenAPI preserves its public information under error.details:

Field errors

field_errors are a structured projection of queue public_error.details[]. The stable fields are:

Public error codes

Generation failures use public error codes from the queue. The table below is synchronized from the queue public error contract.

Common field error types

Field error type values are more granular than top-level code. They may vary by provider and model. Common values include:

Retry strategy

• Do not retry validation or permanent errors without changing the request.
• Retry capacity_exceeded, service_unavailable, generation_failed, and timeout when retryable is true.
• Use the suggested wait in the table as a minimum backoff when the response does not include a more specific delay.
• Use POST /open/v1/generations/{id}/retry for failed generations when retrying the same input.

Troubleshooting