错误

LLMAPI 会尽量返回 HTTP 状态码和结构化错误信息。不同协议会保留对应协议的错误格式，因此错误响应并不只有一种 JSON 形态。

通用错误格式

Anthropic/OpenAI 兼容接口常见格式：

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

OpenAI 图片接口常见格式：

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

Gemini native 路径会返回 Google/Gemini 风格错误，调用方应同时依据 HTTP 状态码和响应体处理错误。

常见 HTTP 状态码

状态码	说明	常见原因
400	请求无效	JSON 不合法、参数类型错误、平台分组不匹配。
401	认证失败	API Key 缺失或无效。
403	权限不足	余额不足、分组未启用生图能力、内容风控拦截。
404	接口或能力不可用	非 OpenAI 分组调用 OpenAI 同步图片接口、OpenAI 分组调用 token count。
409	状态冲突	取消已经结束的异步任务。
413	请求体过大	请求体超过服务端配置上限。
429	限流	并发、等待队列、任务队列或账号容量不足。
500	服务内部错误	未预期错误。
502	上游错误	上游账号或平台返回错误。
503	服务不可用	异步任务未启用、存储未配置、无可用账号。
504	超时	上游或任务执行超时。

异步生图错误

Reason	HTTP 状态	含义
IMAGE_TASKS_DISABLED	503	服务端未启用异步生图。
IMAGE_TASK_STORAGE_UNAVAILABLE	503	OSS/S3 存储未配置或不可用。
IMAGE_TASK_INVALID_REQUEST	400	请求体无效。
IMAGE_TASK_UNSUPPORTED_MODEL	400	请求模型不是支持的图片模型。
IMAGE_TASK_UNSUPPORTED_FEATURE	400	使用了异步任务不支持的能力，例如 multipart 或 stream: true。
IMAGE_TASK_SUBSCRIPTION_UNSUPPORTED	400	异步任务当前不支持订阅计费。
IMAGE_TASK_INSUFFICIENT_BALANCE	403	余额不足，无法预扣。
IMAGE_TASK_QUEUE_LIMIT_EXCEEDED	429	用户或 API Key 达到排队限制，或 n 超过单任务上限。
IMAGE_TASK_ALREADY_TERMINAL	409	任务已结束，不能取消。
IMAGE_TASK_NOT_FOUND	404	任务不存在或不属于当前调用方。

错误示例：

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

平台限制错误

非 OpenAI 分组调用 OpenAI 同步图片接口：

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

OpenAI 分组调用 token count：

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

Gemini native 路径使用非 Gemini 分组：

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

重试建议

错误类型	建议
400、401、403、404	不要原样重试，先修正请求、认证、分组或权限。
409	查询任务最新状态后再决定是否继续。
413	缩小请求体或上传资源。
429	使用指数退避重试，并降低并发或排队任务数。
500、502、503、504	使用指数退避重试；异步生图优先查询任务状态，避免重复提交。

异步生图提交接口如果返回 202，后续请以 task_id 查询任务结果，不要因为客户端超时就立即重复提交同一任务。