# Handle errors and manual review

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

Canonical: https://entirefeed.com/docs/operate/errors-and-manual-review

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](/docs/reference/errors) for stable codes and next actions.

## Read the error envelope

```json
{
  "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_error`: The bearer API key is missing, invalid, inactive, or revoked. Create or replace the organization API key.
- `invalid_request`: The path, body, headers, or task input failed validation. Fix the request using the current task and OpenAPI schemas.
- `task_not_found`: The requested task is not available. Choose a task returned by the tasks endpoint.
- `task_unavailable`: The requested task is visible but not currently runnable. Choose a task marked as available.
- `model_required`: The selected task requires a model. Choose an available model listed for that task.
- `model_not_allowed`: The selected task does not accept a model. Remove the model field and send the task inputs directly.
- `model_not_found`: The requested model is not available. Choose an available model returned by the models endpoint.
- `model_unavailable`: The requested model is visible but not currently runnable. Choose a model marked as available.
- `unsupported_task`: The requested model does not support the selected task. Choose a model listed for that task.
- `insufficient_balance`: Available balance is below the request's current estimate. Add balance in Console or reduce the estimated request.
- `generation_not_found`: The generation does not exist in the key's organization. Check the generation ID and organization credential.
- `workflow_starter_not_found`: The Workflow Starter is not currently published. List starters and choose a returned slug.
- `workflow_run_not_found`: The workflow run does not exist in the key's organization. Check the public run ID and organization credential.
- `webhook_endpoint_not_found`: The webhook endpoint does not exist in the key's organization. List endpoints and use an endpoint ID returned for this organization.
- `idempotency_key_required`: The create or retry request omitted its intent key. Send one stable Idempotency-Key for the intended write.
- `idempotency_conflict`: The same idempotency key was reused for a different intent. Replay the original request or use a new key for new work.
- `starter_version_stale`: The Workflow Starter contract changed. Read the starter, revalidate inputs, and estimate again.
- `workflow_estimate_required`: The workflow run has not been estimated. Estimate the exact intended starter inputs before creation.
- `workflow_estimate_stale`: The workflow estimate no longer matches current pricing. Estimate the same intended inputs again.
- `invalid_workflow_contract`: The published starter contract cannot be executed safely. Stop and report the starter slug and request ID to support.
- `invalid_workflow_inputs`: The inputs do not match the starter's current schema. Read the starter and correct inputs against input_schema.
- `unknown_workflow_cost`: One or more paid steps cannot be estimated. Do not create the run until every cost is known.
- `retry_not_allowed`: The current attempt is not eligible for retry. Read the latest attempt and retry only after it fails or is cancelled.
- `active_retry_exists`: This attempt or a later retry is still active. Monitor the active attempt before deciding on another retry.
- `retry_not_latest`: A newer attempt already exists in this retry sequence. Retry the latest attempt instead.
- `rate_limit_exceeded`: Request volume or active generation concurrency is too high. Reduce concurrency and retry with bounded exponential backoff.
- `invalid_media_upload`: The 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_timeout`: The media upload did not complete within the allowed time. Retry the upload over a stable connection with bounded exponential backoff.
- `media_upload_too_large`: The media file exceeds the current upload size limit. Use a smaller source file before requesting another upload.
- `media_storage_unavailable`: The media file could not be stored temporarily. Retry the upload later with bounded exponential backoff.
- `service_unavailable`: The media service is temporarily unavailable. Retry later with bounded exponential backoff and the same write key.
- `generation_failed`: Accepted work reached a terminal failure. Inspect final usage, then retry only when the generation is eligible.
- `invalid_output`: Completed 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

```json
{
  "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

```json
{
  "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.