错误码

了解接口返回码含义，快速定位请求失败原因。

优先检查 HTTP 状态码与 code 字段

对于 401、403 类错误，请确认密钥状态、权限范围与请求头格式。响应里的 message 是面向用户的中文文案；排查问题请带上 trace_id。

所有错误响应为统一信封格式。错误码是五族闭集（AUTH / QUOTA / TASK / AIRSPACE / SYS），新增错误码会先登记进本表，未登记的码不会出现。

{
  "error": {
    "code": "OP-QUOTA-DAILY-EXHAUSTED",
    "message": "今日试用次数已用完，明天 00:00 重置",
    "trace_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}

OP-TASK-SUBMIT-UNKNOWN 的 HTTP 状态是 202，不是错误：提交结果未知时推理服务可能已受理，谎报失败会让你重复提交、制造重复任务。轮询任务状态即可。

AUTH · 身份与凭据

错误码	HTTP	含义	处理建议
OP-AUTH-REQUIRED	401	请先登录	先完成登录再调用；开放 API 检查是否携带密钥
OP-AUTH-SESSION-EXPIRED	401	登录已过期，请重新登录	重新登录后重试
OP-AUTH-KEY-INVALID	401	密钥无效，请在控制台核对后重试	核对 Authorization 头格式与密钥内容
OP-AUTH-KEY-REVOKED	401	该密钥已被删除，请在控制台重新签发	在控制台重新签发密钥
OP-AUTH-TICKET-INVALID	401	登录凭证无效或已过期，请重新登录	重新发起登录流程
OP-AUTH-TICKET-REPLAYED	401	登录凭证已被使用，请重新登录	登录凭证一次性有效，重新发起登录
OP-AUTH-FORBIDDEN	403	没有访问权限	确认资源归属与账号权限
OP-AUTH-UPSTREAM-DOWN	503	登录服务暂时不可用，请稍后重试	稍后重试；持续失败请联系我们

QUOTA · 额度与并发

错误码	HTTP	含义	处理建议
OP-QUOTA-DAILY-EXHAUSTED	429	今日试用次数已用完，明天 00:00 重置	等待次日重置，或联系我们提升额度
OP-QUOTA-TASK-IN-FLIGHT	409	你有一个任务正在运行，结束后才能开始新任务	先停止或等待在途任务结束
OP-QUOTA-RATE-LIMITED	429	请求过于频繁，请稍后重试	降低频率：空域 60 次/分钟，图片 20 张/分钟、2 个并发批次
OP-QUOTA-KEY-ALREADY-ISSUED	409	已有一把有效密钥；如需更换请使用重置功能	使用重置功能更换密钥

TASK · 任务生命周期

错误码	HTTP	含义	处理建议
OP-TASK-REQUEST-INVALID	400	请求参数有误	检查必填字段、字段类型与幂等键形态；创建直播任务时按 `details.reason` 细分：`stream_url_invalid` 为流地址未通过协议/安全校验，`stream_unreachable` 为连通性探测失败（均未扣减额度）
OP-TASK-SCENE-UNAVAILABLE	400	该场景暂未开放	改用 /api/op/v1/scenes 返回的 enabled 场景
OP-TASK-NOT-FOUND	404	任务不存在	核对 task_id；任务按密钥隔离，跨主体一律 404
OP-TASK-NOT-STOPPABLE	409	任务已结束，无需停止	查询任务状态确认终态
OP-TASK-RESULT-EXPIRED	410	结果已过留存期并被删除	结果保留 90 天，请在留存期内读取
OP-TASK-THRESHOLD-INVALID	400	置信度超出可调范围	min_score 不得低于该任务的推理写入下界
OP-TASK-SUBMIT-UNKNOWN	202	任务已提交，正在确认中	不是错误；勿重发新键，轮询任务状态
OP-TASK-KEY-SEALED	409	该请求已被处理，请勿重复提交	更换幂等键后重新发起
OP-TASK-UPSTREAM-DOWN	503	服务暂时不可用，请稍后重试	稍后重试
OP-TASK-CAPACITY	503	当前使用人数较多，请稍后重试	稍后重试
OP-TASK-BREAKER-OPEN	503	服务维护中，暂停受理新任务	等待平台恢复后再试

AIRSPACE · 空域查询

错误码	HTTP	含义	处理建议
OP-AIRSPACE-REQUEST-INVALID	400	查询参数有误	检查 lon/lat 或 bbox 格式
OP-AIRSPACE-AREA-UNSUPPORTED	400	暂不支持该区域的查询	调整视口范围（不跨 180° 反经线）
OP-AIRSPACE-LAYER-UNAVAILABLE	503	该图层数据暂不可用	稍后重试
OP-AIRSPACE-UPSTREAM-DOWN	503	空域服务暂时不可用，请稍后重试	稍后重试

SYS · 系统

错误码	HTTP	含义	处理建议
OP-SYS-INTERNAL	500	服务异常，请稍后重试	携带 trace_id 联系我们
OP-SYS-UNAVAILABLE	503	服务暂时不可用，请稍后重试	稍后重试；该能力可能尚未开放

未列出的错误码请联系我们，并提供完整请求信息与响应内容。