最近更新时间: 2026-05-21 09:21:02

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) 有专属错误码详细说明

最近更新时间: 2026-05-21 09:21:02

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) 有专属错误码详细说明

公共错误码 & 通用约束

1. 快速查阅区

1.1 HTTP 状态码

1.2 高频业务错误码

2. 详细错误码体系

2.1 通用基础错误 (400xxx)

2.2 域名管理专属错误

2.3 域名配置专属错误

2.4 缓存管理专属错误

2.5 证书管理专属错误

2.6 鉴权错误

2.7 权限/限流错误

2.8 服务端错误

3. 通用约束

3.1 QPS 限制

3.2 操作配额

3.3 时间约束

3.4 格式约束

4. 错误排查流程

本页内容

公共错误码 & 通用约束

1. 快速查阅区

1.1 HTTP 状态码

1.2 高频业务错误码

2. 详细错误码体系

2.1 通用基础错误 (400xxx)

2.2 域名管理专属错误

2.3 域名配置专属错误

2.4 缓存管理专属错误

2.5 证书管理专属错误

2.6 鉴权错误

2.7 权限/限流错误

2.8 服务端错误

3. 通用约束

3.1 QPS 限制

3.2 操作配额

3.3 时间约束

3.4 格式约束

4. 错误排查流程

本页内容