Reference

Error reference

Identify common API and generation error codes, their meaning, and the safe next action.

On this page

Branch on error.code, not message text. Messages add context, while codes are the stable value for integration behavior.

Error response shape

Error envelope

{
  "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"
      }
    ]
  }
}

{
  "properties": {
    "code": {
      "title": "Code",
      "type": "string"
    },
    "message": {
      "title": "Message",
      "type": "string"
    }
  },
  "required": [
    "code",
    "message"
  ],
  "title": "GenerationErrorResponse",
  "type": "object"
}

Common error codes

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

invalid_request400 / 422The path, body, headers, or task input failed validation. Fix the request using the current task and OpenAPI schemas.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

invalid_media_upload400The 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_timeout408The media upload did not complete within the allowed time. Retry the upload over a stable connection with bounded exponential backoff.

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

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

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

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

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