外观
错误码与限流
统一响应
成功响应：
json
{"code":0,"msg":"成功","data":{},"requestId":"..."}失败响应：
json
{"code":"INVALID_REQUEST","msg":"请求参数不正确","data":null,"requestId":"..."}无论成功或失败，都请保留 requestId。后台排查时它比时间和 URL 更容易定位单次请求。
常见错误码
| HTTP | code | 说明 | 处理方式 |
|---|---|---|---|
| 401 | API_KEY_REQUIRED | 未提供密钥 | 添加 Bearer 或 X-API-Key |
| 401 | INVALID_API_KEY | 密钥无效、已轮换或停用 | 从密钥管理器读取当前密钥 |
| 401 | INVALID_AUTH_SCHEME | Authorization 未使用 Bearer | 改成 Authorization: Bearer ... |
| 401 | AMBIGUOUS_API_KEY | 两个请求头的值不一致 | 只保留一个，或保证值一致 |
| 403 | ACCOUNT_UNAVAILABLE | 客户账号被锁定或停用 | 联系管理员处理账号状态 |
| 403 | CUSTOMER_ONLY | 管理员不能申请客户密钥 | 使用客户账号或后台管理能力 |
| 403 | RECHARGE_THRESHOLD_NOT_MET | 累计实付充值未达到门槛 | 充值达到后台配置的门槛后重试 |
| 403 | URL_NOT_OWNED | URL 不属于当前账号网站 | 检查域名归属和拼写 |
| 404 | SITE_NOT_FOUND | 网站不存在或无权访问 | 先查询网站列表 |
| 404 | ENDPOINT_NOT_FOUND | 路径或方法不存在 | 对照接口清单检查 |
| 400 | INVALID_DOMAIN | 域名格式、数量不正确 | 使用合法域名，最多 20 个 |
| 400 | INVALID_PACKAGE | 套餐不存在、过期或非当前账号 | 使用 /packages 返回的 active 套餐 |
| 400 | INVALID_URL | 缓存任务 URL 不是 HTTP(S) | 使用完整 URL |
| 400 | CONFIRMATION_MISMATCH | 删除确认域名不一致 | 原样填写当前域名 |
| 409 | API_KEY_EXISTS | 已有活动密钥 | 轮换或停用旧密钥 |
| 409 | API_KEY_NOT_ACTIVE | 没有可轮换的活动密钥 | 先创建新密钥 |
| 429 | RATE_LIMITED | 超过每分钟请求数 | 等待 Retry-After 后退避重试 |
| 502 | UPSTREAM_ERROR | 上游 CDN 接口错误 | 稍后重试并提交 requestId |
| 503 | OPEN_API_DISABLED | 管理员暂未开放 API | 联系平台管理员 |
| 500 | INTERNAL_ERROR | 服务端未预期错误 | 不要连续重试，反馈 requestId |
限流响应头
每个请求都会返回：
text
X-Request-Id: 请求追踪 ID
X-RateLimit-Limit: 每分钟上限
X-RateLimit-Remaining: 当前窗口剩余次数
X-RateLimit-Reset: Unix 时间戳触发限流时还会返回：
text
Retry-After: 建议等待秒数建议采用指数退避：1 秒、2 秒、4 秒，直到不超过 Retry-After。批量刷新 URL 时控制并发，并优先合并同目录任务。
安全排错清单
- [ ] 请求地址为
https://cdn.1888.news/api/open/v1。 - [ ] 服务器时间准确，未把密钥放在浏览器或前端打包产物中。
- [ ] 账号角色为 customer 且处于启用状态。
- [ ] 套餐和网站属于当前账号。
- [ ] 日志记录了 HTTP 状态、code、requestId 和耗时，但没有记录完整密钥。