Errors

EggAPI returns a consistent response envelope:

{
  "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:

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

Authentication Errors

Missing header:

{
  "data": null,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing Authorization header"
  }
}

Invalid format:

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

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

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:

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

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

Getting Started

Guides

Error Codes

Validation Errors

Authentication Errors

Task Failures

Handling Pattern

​Error Codes

​Validation Errors

​Authentication Errors

​Task Failures

​Handling Pattern

Error Codes

Validation Errors

Authentication Errors

Task Failures

Handling Pattern