错误处理
开放平台对外暴露的所有能力均采用统一的响应与错误格式规范。
1. 响应结构规范
1.1 成功响应 (HTTP 200)
{
"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:
{
"code": 10002,
"error_code": "INVALID_API_KEY",
"message": "访问密钥无效或已过期",
"data": null,
"call_id": "call_94b5952f4dc248dbb4f6236bb5ff64cf"
}字段定义:
| 字段 | 类型 | 说明 |
|---|---|---|
code | integer | 平台统一数字状态码。成功固定为 200;失败时返回 5 位标准业务错误码(如 10002) |
error_code | string | 英文机器识别大写常量(如 INVALID_API_KEY),便于客户端做分支枚举匹配 |
message | string | 面向开发者的错误提示文案 |
data | null | 失败时固定为 null |
call_id | string | 平台单次请求调用的唯一追踪 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 | 服务繁忙,请稍后重试 |
常见核心错误码对照表
code | error_code | HTTP 状态 | 说明及处理建议 |
|---|---|---|---|
10001 | UNAUTHORIZED | 401 | 缺少认证凭据,请提供有效的 Authorization: Bearer <token> 或 x-api-key |
10002 | INVALID_API_KEY | 401 / 403 | API Key 无效、已停用或已删除,请在开放平台控制台核对并重新获取 |
10003 | TOKEN_EXPIRED | 401 | 访问令牌(Access Token)已过期,请重新调用换票接口获取新 Token |
10004 | TOKEN_REVOKED | 401 | 令牌已被主动注销或失效,请重新登录授权 |
10005 | INSUFFICIENT_SCOPE | 403 | API Key 权限不足或未被授权调用当前能力,请在项目设置中开启能力授权 |
10006 | CAPABILITY_FORBIDDEN | 403 | 该能力未对当前项目开放或已被停用 |
10007 | USER_DISABLED | 403 | 账号状态已被禁用,请联系平台管理员 |
10008 | PROJECT_DISABLED | 403 | 项目已被停用,请核对项目状态 |
10009 | CLIENT_TOKEN_REQUIRED | 401 | 端侧调用需要提供有效的 Client Token |
20001 | INVALID_REQUEST | 400 | 请求格式错误或包含非法参数 |
20002 | VALIDATION_ERROR | 422 | 参数校验失败(如缺失必填字段、数值越界),请根据提示检查入参 |
20003 | UNSUPPORTED_MEDIA_TYPE | 415 | 请求媒体类型不受支持(例如文件上传未采用 multipart/form-data) |
20004 | REQUEST_BODY_TOO_LARGE | 413 | 上传的文件或请求体体积超出大小限制,请压缩后重试 |
20005 | RESOURCE_NOT_FOUND | 404 | 请求的路由、文件或资源实体不存在 |
20006 | IDEMPOTENCY_CONFLICT | 409 | 幂等冲突(并发重复提交相同幂等键),请等待上一次请求完成或换用新幂等键 |
30001 | QUOTA_EXHAUSTED | 402 / 403 | 免费试用额度已耗尽,请在控制台进行额度充值 |
30002 | INSUFFICIENT_BALANCE | 402 | 账户钱包余额不足以支付本次能力调用,请及时充值 |
30003 | RATE_LIMIT_EXCEEDED | 429 | 触发 API 频控或并发限制,建议客户端执行指数退避重试 |
50001 | SERVICE_BUSY | 500 / 502 / 503 / 504 | 服务繁忙,请稍后重试;若持续发生请记录 X-Request-ID 联系平台支持 |
3. SSE 错误事件
流式接口(reason-info、if-continue-ask、summary、ai-pic/summary/stream)失败时以终止事件返回:
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,公开数字错误码只出现在任务对象内部:
{
"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 | 含义 | retryable | recommended_action |
|---|---|---|---|
4001 | 请求参数或业务输入不正确 | false | correct_request |
4002 | 身份凭据缺失或无效 | false | sign_in |
4003 | 没有执行当前操作的权限 | false | go_back |
4004 | 请求的资源不存在 | false | go_back |
4005 | 提交的内容超过大小限制 | false | reduce_file_size |
4101 | 当前图片不适合本次识别,请更换符合要求的图片后重试 | false | replace_image |
4102 | 请先选择需要识别的图片 | false | replace_image |
4103 | 图片过大,请压缩或更换图片 | false | reduce_file_size |
4104 | 图片格式不受支持,请更换图片 | false | replace_image |
4105 | 图片内容为空或文件无效,请重新上传 | false | reupload_media |
4106 | 图片地址无效,请重新上传 | false | reupload_media |
4107 | 图片来源不受支持,请重新选择图片 | false | reupload_media |
4108 | 图片暂时无法访问,请重试或重新上传 | true | retry_later |
4501 | 媒体格式或类型不受支持 | false | reupload_media |
4502 | 当前媒体不能用于此业务 | false | reupload_media |
4503 | 媒体文件完整性校验失败 | false | reupload_media |
4504 | 媒体文件超过大小限制 | false | reduce_file_size |
4505 | 媒体文件为空或无法读取 | false | reupload_media |
5001 | 服务暂时不可用,请稍后重试 | true | retry_later |
5002 | 数据库连接繁忙,请稍后重试 | true | retry_later |
5003 | 任务提交失败,请稍后重试 | true | retry_later |
5004 | 依赖服务暂时不可用,请稍后重试 | true | retry_later |
5101 | 图片识别服务响应超时,请稍后重试 | true | retry_later |
5102 | 图片识别服务暂时不可用 | true | retry_later |
5103 | 图片识别配置暂时不可用 | true | retry_later |
5104 | 图片识别结果生成失败,请稍后重试 | true | retry_later |
5105 | 图片报告生成不完整,请稍后重试 | true | retry_later |
5106 | 图片识别连接中断,请重新发起 | true | retry_later |
5401 | 智能问诊连接中断,请重新发起 | true | retry_later |
5501 | 媒体存储服务暂时不可用 | true | retry_later |
5502 | 媒体处理服务暂时不可用 | true | retry_later |
5503 | 媒体处理结果无效,请稍后重试 | true | retry_later |
6001 | 请求与已有任务冲突 | false | use_existing_task |
6002 | 当前任务状态不允许此操作 | false | refresh_state |
6003 | 任务已取消 | false | refresh_state |
6004 | 任务已失效 | false | refresh_state |
6101 | 图片正在分析中,请稍候 | true | wait_and_poll |
6102 | 图片报告任务已经提交 | false | use_existing_task |
6103 | 当前会话的图片识别类型不一致 | false | restart_session |
6106 | 当前会话语言不一致 | false | restart_session |
6501 | 媒体文件尚未准备完成 | true | wait_and_poll |
6502 | 媒体文件与当前任务不匹配 | false | reupload_media |
6503 | 媒体处理阶段尚未满足条件 | true | wait_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 请求头、宠物隐私数据或用户原始敏感信息。