Errors

EggAPI error response format and common failure cases

EggAPI returns a consistent response envelope:

json

{
  "data": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "model bytedance/seedance-2.5/text-to-video requires duration (in seconds) for video generation"
  }
}

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.
`400`	`CONTENT_BLOCKED`	`nsfw_filter` is on and the prompt or an input image did not pass the NSFW filter. Not charged.
`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 task's estimated cost, which is held when the task is created. Top up in the dashboard.
`404`	`NOT_FOUND`	Task or dashboard resource was not found, or it belongs to another account.
`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.
`503`	`MODERATION_UNAVAILABLE`	`nsfw_filter` is on and the filter could not give a verdict. Nothing was generated; retry shortly.

Validation Errors

POST /v1/generate checks:

model: required; must be a published model ID (see Models)
prompt: required, 1 to 100000 characters
negative_prompt: up to 1000 characters
num_outputs: 1 to 16
resolution: one of the model's priced resolutions (see Models)
duration: required for video models; the published video models accept 4 to 15 seconds
image_urls: up to 32 valid URLs; required for edit and image-to-video models
webhook_url: valid URL, up to 2048 characters
nsfw_filter: boolean

Missing duration on a video model:

json

{
  "data": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "model bytedance/seedance-2.5/text-to-video requires duration (in seconds) for video generation"
  }
}

Missing input image on an edit model:

json

{
  "data": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "model google/nano-banana-pro/edit requires image_urls or parameters.images for image-to-image"
  }
}

A model ID that is not published returns 400 VALIDATION_ERROR with a message that starts with unsupported model. Check the ID against the model list.

Authentication Errors

Missing header:

json

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

Invalid format:

json

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

{
  "data": {
    "id": "gen_3f2a9c1d-7b4",
    "status": "failed",
    "model": "google/nano-banana-2/text-to-image",
    "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

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

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

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

← Workflow Skills API Reference →