Errors

LLMAPI returns HTTP status codes and structured error information where possible. Different protocols keep their corresponding error shapes, so there is not only one JSON error format.

Common Error Shapes

Anthropic/OpenAI compatible endpoints often return:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Request body is empty"
  }
}

OpenAI image endpoints often return:

{
  "error": {
    "type": "not_found_error",
    "message": "Images API is not supported for this platform"
  }
}

Gemini native paths return Google/Gemini style errors. Clients should inspect both HTTP status and response body.

Common HTTP Status Codes

Status	Meaning	Common causes
400	Invalid request	Invalid JSON, wrong parameter type, or platform group mismatch.
401	Authentication failed	Missing or invalid API key.
403	Permission denied	Insufficient balance, image generation disabled, or content moderation blocked.
404	Endpoint or capability unavailable	Non-OpenAI group calling OpenAI synchronous image endpoints, or OpenAI group calling token count.
409	State conflict	Canceling an async task that already finished.
413	Request body too large	Request exceeds the configured body limit.
429	Rate limited	Concurrency, wait queue, task queue, or upstream account capacity limits.
500	Internal error	Unexpected server error.
502	Upstream error	Upstream account or platform returned an error.
503	Service unavailable	Async tasks disabled, storage not configured, or no available accounts.
504	Timeout	Upstream or task execution timed out.

Async Image Task Errors

Reason	HTTP status	Meaning
IMAGE_TASKS_DISABLED	503	Async image tasks are disabled in server config.
IMAGE_TASK_STORAGE_UNAVAILABLE	503	OSS/S3 storage is not configured or unavailable.
IMAGE_TASK_INVALID_REQUEST	400	Request body is invalid.
IMAGE_TASK_UNSUPPORTED_MODEL	400	Requested model is not a supported image model.
IMAGE_TASK_UNSUPPORTED_FEATURE	400	Request uses an unsupported async-task feature, such as multipart or stream: true.
IMAGE_TASK_SUBSCRIPTION_UNSUPPORTED	400	Async tasks currently do not support subscription billing.
IMAGE_TASK_INSUFFICIENT_BALANCE	403	Balance is insufficient for reservation.
IMAGE_TASK_QUEUE_LIMIT_EXCEEDED	429	User or API key queue limit was reached, or n exceeds the per-task limit.
IMAGE_TASK_ALREADY_TERMINAL	409	Task is already finished and cannot be canceled.
IMAGE_TASK_NOT_FOUND	404	Task does not exist or does not belong to the caller.

Error example:

{
  "error": {
    "type": "IMAGE_TASK_INVALID_REQUEST",
    "message": "prompt must be a non-empty string"
  }
}

Platform Restriction Errors

Non-OpenAI group calling an OpenAI synchronous image endpoint:

{
  "error": {
    "type": "not_found_error",
    "message": "Images API is not supported for this platform"
  }
}

OpenAI group calling token count:

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "Token counting is not supported for this platform"
  }
}

Non-Gemini group calling Gemini native paths:

{
  "error": {
    "message": "API key group platform is not gemini"
  }
}

Retry Guidance

Error type	Recommendation
400, 401, 403, 404	Do not retry unchanged; fix request, authentication, group, or permission first.
409	Fetch the latest task state before deciding what to do next.
413	Reduce request body or uploaded resource size.
429	Retry with exponential backoff and reduce concurrency or queued tasks.
500, 502, 503, 504	Retry with exponential backoff; for async images, query task status first to avoid duplicate submissions.

If an async image submit request returned 202, use the returned task_id for follow-up checks instead of immediately submitting a duplicate task after a client-side timeout.