# Error reference

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

Canonical: https://entirefeed.com/docs/reference/errors

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

## Error response shape

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

Generation error schema:

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

## Common error codes

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