CDN

    • CDN > API 文档 > 公共错误码 & 通用约束

    公共错误码 & 通用约束

    最近更新时间: 2026-03-25 14:06:08

    1. 快速查阅区

    1.1 HTTP 状态码

    HTTP 状态码 含义 责任方 处理方式
    200 成功 - 正常处理返回数据
    400 请求参数错误 调用方 按接口文档修正参数，检查 JSON 格式
    401 鉴权失败 调用方 检查 AK/SK、签名算法、鉴权方式与域名匹配
    403 权限不足 / QPS 超限 调用方 检查账号权限或降低调用频率
    404 资源不存在 调用方 检查域名/证书ID/任务ID 拼写
    405 请求方法错误 调用方 按接口文档指定的方法调用
    429 请求频率超限 调用方 降低调用频率
    500 服务端内部错误 七牛云 记录 X-Reqid，稍后重试
    503 服务暂不可用 七牛云 等待后重试，关注官网公告

    1.2 高频业务错误码

    错误码 错误描述 所属模块 解决方案
    400013 重复操作 域名管理 域名已处于目标状态 (如已下线再下线)，无需处理
    400020 域名未备案 域名管理 完成 ICP 备案，或 geoCover 设为 foreign 免备案
    400030 正在处理中 域名管理 上一操作未完成 (5-10分钟)，等待后重试
    400031 invalid url 缓存管理 检查 URL 格式，须为完整 http:// 或 https://
    400033 预取配额超限 缓存管理 次日恢复，或控制台申请提升配额
    400034 刷新配额超限 缓存管理 次日恢复，或控制台申请提升配额
    400035 目录刷新配额超限 缓存管理 同上
    400038 无目录刷新权限 缓存管理 控制台开通「目录刷新」功能
    400041 源站测试路径不可访问 域名管理 testURLPath 须以 / 开头，源站需返回 200
    400062 重复域名 域名管理 域名已存在，无需重复创建
    400309 缓存规则未设置全局 域名配置 cacheControls 须包含 type=all 的全局兜底规则
    400317 非已下线的域名 域名管理 删除/上线前须先下线域名
    400323 证书链验证失败 证书管理 拼接完整 PEM 证书链 (服务器→中间→根证书)
    400401 无此证书 证书管理 检查 certId 正确性，证书可能已删除
    401001 签名不匹配 鉴权 检查签名串拼接、AK/SK 正确性
    401002 鉴权头无效 鉴权 检查 Authorization 格式，Qiniu/QBox 后有空格
    403024 单用户 QPS 超限 全局 降低频率，api 10QPS / fusion 5-10QPS
    404001 资源不存在 全局 检查域名/证书ID/任务ID 拼写
    500000 服务端内部错误 全局 记录 X-Reqid，稍后重试，或提交工单

    2. 详细错误码体系

    2.1 通用基础错误 (400xxx)

    错误码 错误描述 详细排查
    400000 无效输入参数 参数值为空、参数组合不符合规则
    400001 参数解析错误 请求体非紧凑 JSON、语法错误、缺少 Content-Type
    400032 无效域名 域名格式错误、未接入 CDN、不归属当前账号
    400080 开始时间格式错误 时间参数须为 yyyy-MM-dd 格式
    400081 结束时间格式错误 同上
    400082 时间范围错误 开始时间 ≥ 结束时间，或跨度超出限制
    400203 账号已禁用 因违规/欠费被限制，联系客服

    2.2 域名管理专属错误

    错误码 错误描述 场景 解决方案
    400013 重复操作 已下线的域名再下线 已处于目标状态，无需处理
    400020 域名未备案 geoCover=china/global 时 完成 ICP 备案，或改用 foreign
    400030 正在处理中 上一操作 (创建/上下线) 未完成 等待 5-10 分钟后重试
    400041 源站测试路径不可访问 创建域名时 testURLPath 不可达 确保源站路径返回 200
    400095 未知的父域名 创建泛子域名时 检查 pareDomain 格式 (以 . 开头)
    400062 重复域名 重复创建同名域名 已存在，无需重复创建
    400317 非已下线的域名 删除/上线未下线的域名 须先下线再操作
    400412 无效的泛子域名 泛子域名格式错误 仅支持一级子域名

    2.3 域名配置专属错误

    错误码 错误描述 场景 解决方案
    400042 配置参数错误 缓存规则/防盗链格式不符 检查参数格式符合接口要求
    400309 缓存规则未设置全局 PUT /cache 缺少 type=all 兜底 cacheControls 须含 type=all 的全局规则
    400324 证书不存在/已过期 sslize 时 certId 无效 重新上传有效证书
    400302 更改证书失败 httpsconf 时域名未开启 HTTPS 需先 sslize 开启 HTTPS
    400916 http协议不允许降级 unsslize 时域名未开启 HTTPS 域名未开启 HTTPS，无需降级
    500235 该域名未绑定证书 sslize 时域名未绑定证书 需先上传并绑定证书
    400520 互斥配置冲突 同时设置时间戳和回源鉴权 两者互斥，只能启用其一

    2.4 缓存管理专属错误

    错误码 错误描述 场景 解决方案
    400031 invalid url 刷新 URL 格式错误 须为完整 http:// 或 https:// URL
    400033 预取配额超限 每日预取次数超限 次日恢复，或控制台申请提升
    400034 刷新配额超限 每日刷新次数超限 次日恢复，或控制台申请提升
    400035 目录刷新配额超限 目录刷新次数超限 同上
    400038 无目录刷新权限 未开通目录刷新功能 控制台→CDN→功能管理开通

    2.5 证书管理专属错误

    错误码 错误描述 场景 解决方案
    400323 证书链验证失败 上传证书时链不完整 按 服务器→中间→根 拼接完整 PEM
    400401 无此证书 certId 不存在 检查 ID 拼写，或证书已删除

    2.6 鉴权错误

    错误码 错误描述 详细排查
    401000 账号未实名认证 控制台→个人中心→实名认证
    401001 签名不匹配 ① AK/SK 正确性 ② 签名串拼接格式 ③ Base64 编码 ④ 服务器时间
    401002 鉴权头无效 ① 鉴权方式与域名匹配 (api→Qiniu, fusion→QBox) ② 格式含空格
    401003 access_token 无效 QBox token 路径与实际请求路径不一致
    401004 时间戳过期 同步 NTP，UTC 偏差 ≤ 30s

    2.7 权限/限流错误

    错误码 错误描述 详细排查
    403001 无操作权限 子账号需分配 CDN 管理权限
    403022 全局 QPS 超限 稍后重试
    403024 单用户 QPS 超限 降低频率，批量操作，或申请提升

    2.8 服务端错误

    错误码 错误描述 处理方式
    500000 服务端内部错误 记录 X-Reqid，等 1-2 分钟重试，多次失败提工单
    500005 服务端查询数据错误 稍后重试
    503001 服务暂不可用 平台维护，等 5-10 分钟重试
    504001 网关超时 临时网络波动，立即重试

    3. 通用约束

    3.1 QPS 限制

    请求域名 QPS 超限错误码 处理
    api.qiniu.com 10 403024 批量操作 + 异步调用
    fusion.qiniuapi.com 5-10 403024 同上

    主账号和子账号共享同一 QPS 配额。

    3.2 操作配额

    操作 默认每日配额 超限错误码 提升方式
    文件刷新 500 次/天 400034 控制台→CDN→配额管理
    目录刷新 需开通 400035 同上 (需先开通)
    资源预取 100 次/天 400033 同上

    配额每日 0 点自动重置。

    3.3 时间约束

    约束项 规则
    日期格式 yyyy-MM-dd (如 2026-02-13)
    鉴权时间戳偏差 ≤ 30 秒
    日志保留 30 天
    统计数据保留 计费数据 180 天，监控数据 90 天，运营统计 90 天
    用量统计时间跨度 ≤ 31 天
    运营统计时间跨度 ≤ 30 天
    配置生效时间 5-10 分钟

    3.4 格式约束

    约束项 规则
    请求体 紧凑 JSON (无格式化空格/换行)，携带 Content-Type: application/json
    刷新/预取 URL 完整 http:// 或 https:// 格式
    SSL 证书 PEM 格式，含完整证书链
    源站测试路径 以 / 开头的相对路径
    字符编码 UTF-8

    4. 错误排查流程

    1. 看 HTTP 状态码
   ├─ 5xx → 记录 X-Reqid，等待重试
   └─ 4xx → 继续排查 ↓

2. 看业务错误码
   ├─ 401xxx → 检查鉴权 (AK/SK、签名、域名匹配)
   ├─ 403xxx → 检查权限/QPS
   ├─ 404xxx → 检查资源标识
   └─ 400xxx → 检查参数 ↓

3. 看 error 描述
   └─ 中文描述直接说明原因 (如 "域名未备案""缓存规则未设置全局")

4. 查对应模块文档
   └─ 各模块文档 (03-09) 有专属错误码详细说明
    以上内容是否对您有帮助？