错误

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

任务 API 业务错误常见格式如下；认证失败仍使用 authentication_error：

{
  "error": {
    "type": "TASK_INVALID_REQUEST",
    "message": "params is required"
  }
}

常见 HTTP 状态码

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

任务 API 错误

Reason	HTTP 状态	含义
authentication_error	401	API Key 缺失或无效。
TASKS_DISABLED	503	服务端未启用任务 API。
TASKS_PAUSED	503	任务 API 处理暂时暂停。
TASK_SCOPE_REQUIRED	403	当前 API Key 未启用任务 API。
TASK_INVALID_REQUEST	400	请求体无效。
TASK_UNSUPPORTED_MODEL	400	请求模型不可用于任务 API。
TASK_UNSUPPORTED_ADAPTER	400	请求模型不支持该任务类型。
TASK_NO_CAPABLE_ROUTE	400	当前渠道无法完整支持请求参数或输入素材组合。
TASK_PRICING_UNAVAILABLE	503	请求模型或参数暂无可用价格。
TASK_STORAGE_UNAVAILABLE	503	结果资产存储不可用。
TASK_INSUFFICIENT_BALANCE	403	余额不足，无法覆盖任务预估费用。
TASK_QUEUE_LIMIT_EXCEEDED	429	用户或 API Key 达到排队限制。
TASK_ALREADY_TERMINAL	409	任务已结束，不能取消。
TASK_NOT_FOUND	404	任务不存在，或当前 API Key 无权访问。

平台限制错误

非 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"
  }
}

重试建议

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

POST /v1/tasks 如果返回 202，后续请以返回的 id 查询任务结果，不要因为客户端超时就立即重复提交同一任务。