Skip to main content

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.

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 statusCodeTypical cause
400BAD_REQUESTMissing path/query data or malformed request.
400VALIDATION_ERRORJSON body failed validation.
401UNAUTHORIZEDMissing, malformed, inactive, expired, or invalid credentials.
403FORBIDDENUser account is suspended or the session lacks permission.
403INSUFFICIENT_BALANCEBalance cannot cover the generated result.
404NOT_FOUNDTask or dashboard resource was not found.
429RATE_LIMITEDAPI key or IP rate limit was exceeded.
500INTERNAL_ERRORBackend, database, queue, or storage failure.
502UPSTREAM_ERRORUpstream provider returned a gateway failure.
503SERVICE_UNAVAILABLEService 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");
}