错误码说明
更新时间:2026-09-22
code 为业务错误码。请一律按 code 分流,不要按 HTTP 状态码分流。
| code | HTTP | 是否可重试 | 说明 | 典型场景 |
|---|---|---|---|---|
| success | 200 / 202 | - | 成功 | 请求处理成功 |
| ParamMissing | 200 | 不可重试 | 缺少必填参数 | 未传slug/sha256、source_url、task_ids、file 等 |
| ParamError | 200 | 不可重试 | 参数格式错误 | 格式不合法、列表超过 100、文件不是 zip、文件超限;用量查询时间跨度超 1 年、月份格式非法、起止时间倒置等 |
| DownloadFailed | 200 | 可重试 | 下载失败 | source_url 下载失败、网络不可达或权限不足 |
| DownloadTimeout | 200 | 可重试 | 下载超时 | source_url 下载超时 |
| EngineError | 200 | 可重试 | 扫描引擎内部错误 | 扫描引擎处理异常 |
| TaskNotFound | 200 | 不可重试 | 任务不存在 | 请求级别的任务不存在;批量查询任务状态接口不用该码,改在对应项返回status: not_found |
| Conflict | 200 | 不可重试 | 资源冲突 | 同一 hash 已存在其它类型的有效记录 |
| Unauthorized | 401 | 不可重试 | 认证失败 | 签名错误、签名过期、AK 无效 |
| Forbidden | 403 | 不可重试 | 禁止访问 | 调用方或权限校验失败 |
| NotSubscribed | 403 | 不可重试 | 未开通本服务 | 该账号从未购买 Skill 安全检测服务,需先到控制台开通。只有计费接口返回(results/upload/scan/batch) |
| ServiceStopped | 403 | 不可重试 | 服务已停服 | 账号欠费或资源已停服,充值后自动恢复。只有计费接口返回(results/upload/scan/batch) |
| DependencyUnavailable | 503 | 可重试 | 依赖服务暂时不可用 | 订阅状态无法判定等内部依赖故障,稍后重发即可 |
| InternalError | 200 | 可重试 | 服务端未知错误 | 服务端内部异常 |
三种 403 的区别
都是 403,但处置动作完全不同:
NotSubscribed:需下单开通。ServiceStopped:需充值。Forbidden:签名身份或权限本身不被允许。
NotSubscribed 与 ServiceStopped 只出现在三个计费接口(results/upload/scan/batch)。不计费的 tasks/batch 与 usage 不做订阅态校验,验签通过即放行——未开通、已停服、已释放的账号都能调,用于核对用量与取回既有任务结果;这两个接口只会因验签失败(401 Unauthorized)或我方依赖故障(503 DependencyUnavailable,可重试)被拒。
错误响应体
JSON
1{
2 "code": "ParamMissing",
3 "message": "Parameter 'slug' or 'sha256' is required",
4 "ts": 1786362673044
5}
评价此篇文章
