> ## Documentation Index
> Fetch the complete documentation index at: https://docs.eggapi.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> EggAPI error response format and common failure cases

EggAPI returns a consistent response envelope:

```json theme={null}
{
  "data": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Key: 'GenerateRequest.Model' Error:Field validation for 'Model' failed on the 'oneof' tag"
  }
}
```

Successful responses use the same envelope with `error: null`.

## Error Codes

| HTTP status | Code                   | Typical cause                                                  |
| ----------- | ---------------------- | -------------------------------------------------------------- |
| `400`       | `BAD_REQUEST`          | Missing path/query data or malformed request.                  |
| `400`       | `VALIDATION_ERROR`     | JSON body failed validation.                                   |
| `401`       | `UNAUTHORIZED`         | Missing, malformed, inactive, expired, or invalid credentials. |
| `403`       | `FORBIDDEN`            | User account is suspended or the session lacks permission.     |
| `403`       | `INSUFFICIENT_BALANCE` | Balance cannot cover the generated result.                     |
| `404`       | `NOT_FOUND`            | Task or dashboard resource was not found.                      |
| `429`       | `RATE_LIMITED`         | API key or IP rate limit was exceeded.                         |
| `500`       | `INTERNAL_ERROR`       | Backend, database, queue, or storage failure.                  |
| `502`       | `UPSTREAM_ERROR`       | Upstream provider returned a gateway failure.                  |
| `503`       | `SERVICE_UNAVAILABLE`  | Service temporarily unavailable.                               |

## Validation Errors

The generation request currently validates:

* `model`: `nanobanana`
* `prompt`: required, 1 to 2000 characters
* `negative_prompt`: up to 1000 characters
* `num_outputs`: 1 to 4
* `duration`: 1 to 60
* `aspect_ratio`: `16:9` or `9:16`
* `resolution`: `1k`, `2k`, or `4k`
* `image_urls`: up to 9 valid URLs
* `webhook_url`: valid URL, up to 2048 characters

Example invalid model:

```json theme={null}
{
  "data": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Key: 'GenerateRequest.Model' Error:Field validation for 'Model' failed on the 'oneof' tag"
  }
}
```

## Authentication Errors

Missing header:

```json theme={null}
{
  "data": null,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing Authorization header"
  }
}
```

Invalid format:

```json theme={null}
{
  "data": null,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid Authorization format, expected 'Bearer <token>'"
  }
}
```

## Task Failures

A failed generation task is returned as successful HTTP `200` from `GET /v1/tasks/{id}` because the task lookup succeeded. The failure is represented inside `data.status` and `data.error`.

```json theme={null}
{
  "data": {
    "id": "gen_abc123def456",
    "status": "failed",
    "model": "nanobanana",
    "type": "image_generate",
    "error": "generation failed: upstream provider unavailable",
    "cost": "$0.00",
    "created_at": "2026-05-08T10:30:00Z",
    "started_at": "2026-05-08T10:30:01Z",
    "completed_at": "2026-05-08T10:30:12Z"
  },
  "error": null
}
```

## Handling Pattern

```javascript theme={null}
async function eggapi(request) {
  const response = await fetch(request);
  const body = await response.json();

  if (body.error) {
    throw new Error(`${body.error.code}: ${body.error.message}`);
  }

  return body.data;
}
```

For task polling, check both the HTTP response envelope and the task status:

```javascript theme={null}
const task = await eggapi(`https://api.eggapi.ai/v1/tasks/${taskId}`);

if (task.status === "failed") {
  throw new Error(task.error || "EggAPI task failed");
}
```