Skip to content

错误处理 ​

开放平台对外暴露的所有能力均采用统一的响应与错误格式规范。

1. 响应结构规范 ​

1.1 成功响应 (HTTP 200) ​

json
{
  "code": 200,
  "message": "success",
  "data": { ... }
}
  • code:固定为 200,表示业务处理成功。
  • message:固定为 "success"。
  • data:具体的业务返回数据对象或数组。

1.2 失败响应 (HTTP 200) ​

为了简化客户端与各语言 SDK 的处理逻辑,平台在网络连通情况下,HTTP 状态码统一返回 200 OK。调用是否成功完全由响应体中的 code 决定;失败时统一返回包含 code、error_code、message、data: null 以及全局链路追踪唯一凭证 call_id:

json
{
  "code": 10002,
  "error_code": "INVALID_API_KEY",
  "message": "访问密钥无效或已过期",
  "data": null,
  "call_id": "call_94b5952f4dc248dbb4f6236bb5ff64cf"
}

字段定义:

字段类型说明
codeinteger平台统一数字状态码。成功固定为 200;失败时返回 5 位标准业务错误码(如 10002)
error_codestring英文机器识别大写常量(如 INVALID_API_KEY),便于客户端做分支枚举匹配
messagestring面向开发者的错误提示文案
datanull失败时固定为 null
call_idstring平台单次请求调用的唯一追踪 ID(以 call_ 开头),与请求响应头中的 X-QJ-Request-ID 一致,用于问题排查与技术支持

错误判断建议

客户端与 SDK 请统一使用 res.code === 200 判定请求是否成功;网络请求库不会触发非 200 的异常 reject,可直接在业务层判断 code 并根据 error_code 进行针对性处理。


2. 统一业务错误号段与错误码 ​

开放平台统一错误码按功能域划分为 5 个标准号段:

号段范围分类HTTP 映射核心用途与场景
200成功200业务正常执行完毕
10000 ~ 19999认证与鉴权 (Auth)401 / 403身份凭据缺失、密钥无效、Token 过期、无能力权限或账号封禁
20000 ~ 29999请求与参数 (Request)400 / 415 / 422请求体结构错误、必填字段缺失、媒体类型不支持、资源不存在
30000 ~ 39999配额与计费 (Billing)402 / 429试用次数用尽、账户余额不足、QPS 限流拦截
50000 ~ 59999服务与系统维护 (System)500 / 502 / 503 / 504服务繁忙,请稍后重试

常见核心错误码对照表 ​

codeerror_codeHTTP 状态说明及处理建议
10001UNAUTHORIZED401缺少认证凭据,请提供有效的 Authorization: Bearer <token> 或 x-api-key
10002INVALID_API_KEY401 / 403API Key 无效、已停用或已删除,请在开放平台控制台核对并重新获取
10003TOKEN_EXPIRED401访问令牌(Access Token)已过期,请重新调用换票接口获取新 Token
10004TOKEN_REVOKED401令牌已被主动注销或失效,请重新登录授权
10005INSUFFICIENT_SCOPE403API Key 权限不足或未被授权调用当前能力,请在项目设置中开启能力授权
10006CAPABILITY_FORBIDDEN403该能力未对当前项目开放或已被停用
10007USER_DISABLED403账号状态已被禁用,请联系平台管理员
10008PROJECT_DISABLED403项目已被停用,请核对项目状态
10009CLIENT_TOKEN_REQUIRED401端侧调用需要提供有效的 Client Token
20001INVALID_REQUEST400请求格式错误或包含非法参数
20002VALIDATION_ERROR422参数校验失败(如缺失必填字段、数值越界),请根据提示检查入参
20003UNSUPPORTED_MEDIA_TYPE415请求媒体类型不受支持(例如文件上传未采用 multipart/form-data)
20004REQUEST_BODY_TOO_LARGE413上传的文件或请求体体积超出大小限制,请压缩后重试
20005RESOURCE_NOT_FOUND404请求的路由、文件或资源实体不存在
20006IDEMPOTENCY_CONFLICT409幂等冲突(并发重复提交相同幂等键),请等待上一次请求完成或换用新幂等键
30001QUOTA_EXHAUSTED402 / 403免费试用额度已耗尽,请在控制台进行额度充值
30002INSUFFICIENT_BALANCE402账户钱包余额不足以支付本次能力调用,请及时充值
30003RATE_LIMIT_EXCEEDED429触发 API 频控或并发限制,建议客户端执行指数退避重试
50001SERVICE_BUSY500 / 502 / 503 / 504服务繁忙,请稍后重试;若持续发生请记录 X-Request-ID 联系平台支持

3. SSE 错误事件 ​

流式接口(reason-info、if-continue-ask、summary、ai-pic/summary/stream)失败时以终止事件返回:

text
data: {"type":"error","code":"AI_DOC_CONTINUE_STREAM_FAILED","error_code":5401,"message":"流式判断是否继续追问失败","retryable":true,"recommended_action":"retry_later"}
事件类型说明数据格式
error流式接口的失败终止事件;retryable 为 true 时可有限重试{"type":"error","code":"<INTERNAL_CODE>","error_code":<PUBLIC_CODE>,"message":"失败原因","retryable":true,"recommended_action":"retry_later"}

收到 error 或连接在结束前断开,都不要进入下一步。error_code 取值见任务级错误码。

4. 任务级错误码 ​

异步任务失败时,HTTP 仍是 200、code 也是 200,公开数字错误码只出现在任务对象内部:

json
{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "<TASK_ID>",
    "status": "failed",
    "error_code": 5105
  }
}
  • 判定失败看 data.status(failed / canceled),不要看 HTTP 状态码或 code。
  • data.error_code:任务失败时的公开数字错误码;任务未失败时为 null。
  • 统一响应只有 code、message、data 三个字段,没有顶层 error_code;任务是否失败必须解析 data。

用 GET /ai-tasks/{task_id} 读取。任务对象不再返回内部原因标识、错误文案、retryable 与 recommended_action;是否可重试请按下表(平台公开契约)判断。

error_code含义retryablerecommended_action
4001请求参数或业务输入不正确falsecorrect_request
4002身份凭据缺失或无效falsesign_in
4003没有执行当前操作的权限falsego_back
4004请求的资源不存在falsego_back
4005提交的内容超过大小限制falsereduce_file_size
4101当前图片不适合本次识别,请更换符合要求的图片后重试falsereplace_image
4102请先选择需要识别的图片falsereplace_image
4103图片过大,请压缩或更换图片falsereduce_file_size
4104图片格式不受支持,请更换图片falsereplace_image
4105图片内容为空或文件无效,请重新上传falsereupload_media
4106图片地址无效,请重新上传falsereupload_media
4107图片来源不受支持,请重新选择图片falsereupload_media
4108图片暂时无法访问,请重试或重新上传trueretry_later
4501媒体格式或类型不受支持falsereupload_media
4502当前媒体不能用于此业务falsereupload_media
4503媒体文件完整性校验失败falsereupload_media
4504媒体文件超过大小限制falsereduce_file_size
4505媒体文件为空或无法读取falsereupload_media
5001服务暂时不可用,请稍后重试trueretry_later
5002数据库连接繁忙,请稍后重试trueretry_later
5003任务提交失败,请稍后重试trueretry_later
5004依赖服务暂时不可用,请稍后重试trueretry_later
5101图片识别服务响应超时,请稍后重试trueretry_later
5102图片识别服务暂时不可用trueretry_later
5103图片识别配置暂时不可用trueretry_later
5104图片识别结果生成失败,请稍后重试trueretry_later
5105图片报告生成不完整,请稍后重试trueretry_later
5106图片识别连接中断,请重新发起trueretry_later
5401智能问诊连接中断,请重新发起trueretry_later
5501媒体存储服务暂时不可用trueretry_later
5502媒体处理服务暂时不可用trueretry_later
5503媒体处理结果无效,请稍后重试trueretry_later
6001请求与已有任务冲突falseuse_existing_task
6002当前任务状态不允许此操作falserefresh_state
6003任务已取消falserefresh_state
6004任务已失效falserefresh_state
6101图片正在分析中,请稍候truewait_and_poll
6102图片报告任务已经提交falseuse_existing_task
6103当前会话的图片识别类型不一致falserestart_session
6106当前会话语言不一致falserestart_session
6501媒体文件尚未准备完成truewait_and_poll
6502媒体文件与当前任务不匹配falsereupload_media
6503媒体处理阶段尚未满足条件truewait_and_poll

retryable 为 true 的任务用 POST /ai-tasks/{task_id}/retry 重试;为 false 时重试不会成功,应按 recommended_action 修正输入或重建会话。

5. 排查信息 ​

记录以下内容:HTTP 状态码与响应体 code(任务失败时记录 data.status 与 data.error_code)、message、请求时间、接口路径,以及本次调用的 session_id / task_id / 报告 ID。

日志脱敏

日志中不得记录完整的 x-api-key、Authorization 请求头、宠物隐私数据或用户原始敏感信息。

最近更新

栖界开放平台 · API Documentation