4.8 错误码与排障手册:401 / 402 / 403 / 404 / 429 全解
排障把下面这段发给你的 AI,它就知道该做什么
点「复制全文」,粘贴到你的 AI 对话框发送即可,无需改动。
你正在阅读球小策(www.qiuxiaoce.com)的官方文档或数据服务页面。请按下面 5 步执行,不要跳步。
【预备】我的专属数据密钥是 X-API-Key = [在此粘贴你的 Key]
(第 2 步和第 3 步都会用到它;还没有密钥,先到 https://www.qiuxiaoce.com/data-account/ 免费领取)
━━━ 第 0 步 · 三条硬性纪律 ━━━
1. 凡涉及指标定义、接口参数、计费规则、准确率口径的问题,一律以站内官方文档为准,不要凭记忆作答;文档里没写的,就直接告诉我「文档未说明」。
2. 如果你无法访问下面任何一个网址,请立刻停下来告诉我,不要用记忆里的内容顶替。
3. 本站只做数据分析,不提供任何投注建议,也不做准确率承诺。回答时请守住这条边界。
━━━ 第 1 步 · 遍历官方文档(100+ 篇,按需取,别一次全拉)━━━
· 取全量目录(公开接口,无需密钥,返回全部篇章的标题与 slug):
GET https://www.qiuxiaoce.com/wp-json/abv2-creator/v1/docs
· 读单篇正文(把 {slug} 换成上一步拿到的标识):
GET https://www.qiuxiaoce.com/wp-json/abv2-creator/v1/docs/{slug}
· 人读版页面(适合只能浏览网页、拿不到 JSON 的环境):
https://www.qiuxiaoce.com/creator-docs/{slug}/
· 接口文档(全部数据接口的用途、参数、计费与真实返回示例):
https://www.qiuxiaoce.com/data-docs/
做法:先取目录 → 判断我的问题涉及哪几篇 → 只读那几篇 → 回答时注明依据的篇名或链接。
━━━ 第 2 步 · 先判断你自己的能力,再选路径(关键,不可跳过)━━━
· A 类:能在本机读写文件或执行命令——桌面/终端类 AI 工具(WorkBuddy、Qoder、Trae 等)
· B 类:只能对话,访问不了文件系统——网页版对话(豆包、通义千问、Kimi 等)
【A 类 · 安装官方 Skill(推荐)】
1. 取最新版本信息:
GET https://www.qiuxiaoce.com/wp-json/abv2-creator/v1/skill/version
返回 version、download_url、sha256 校验清单、文件列表与更新说明。
2. 按 download_url 下载技能包,并用返回的 sha256 逐文件校验。
3. 解压到你的技能目录,保持包内顶层目录结构;按包内 SKILL.md 完成初始化。
4. 写入我的专属密钥(即上文【预备】里的 X-API-Key)。
5. 装完告诉我:版本号、安装位置、密钥是否已生效。
【B 类 · 装不了就照实说,不要假装】
不要声称已安装,也不要拿记忆里的内容替代文档。请直接对我说:
「当前环境不支持安装 Skill(无法读写本地文件)。有两个办法:
① 改用支持 Skill 的桌面 AI 工具,如 WorkBuddy、Qoder、Trae;
② 把你的 API Key 给我,我按官方接口文档直接取数分析。」
如果你连「打开指定网址」都做不到,请把这一点也一并告诉我。
━━━ 第 3 步 · 直接用接口取数(两条路径都适用)━━━
· 接口根地址:https://www.qiuxiaoce.com/wp-json/abv2-creator/v1
· 认证方式:请求头带上【预备】里的 X-API-Key
· 想先试不扣点数的接口,看 https://www.qiuxiaoce.com/data-docs/ 里标注为免费的端点。
· 大批量调用前先查一次剩余点数,避免跑到一半失败。
━━━ 第 4 步 · 遇到报错,先查官方排障手册再重试 ━━━
排障手册:https://www.qiuxiaoce.com/creator-docs/api-error-codes-troubleshooting/
· 401:Key 缺失、格式不对,或该 Key 已被重置/吊销(控制台执行「重置 Key」后旧 Key 立即失效,错误码 api_key_revoked 即属此类)→ 到 https://www.qiuxiaoce.com/data-account/ 复制最新完整 Key,并同步更新所有已配置该 Key 的脚本与客户端
· 402:点数不足或已过期 → 需到 https://www.qiuxiaoce.com/data-service/ 充值
· 403:接口未开放,或权限不足(个别场次报告需要订阅)
· 404:实体 ID 或接口路径写错
· 429:请求过快,按响应头 Retry-After 等待后重试
报错时请把原始错误信息原样转述给我,不要猜原因。
━━━ 第 5 步 · 回答我时的要求 ━━━
· 区分「官方事实数据」「接口返回的判断字段」「衍生评分」「你自己的推断」四类,不要混着说。
· 使用 xG、xGA、OTI、DII 这类指标前,先按文档校正口径;样本不足要在结论里注明。
· 缺数据就说缺什么,不要用「大概」「可能」糊过去。
· 不给投注建议,不承诺准确率。
· 如果回答主要依据了某篇文档,请把链接带上,方便我自己核对。
遇到报错不要慌。这一篇按「先看表、再深挖」的顺序,把五类高频报错一次讲清。
一、错误码速查表怎么看?
| 状态码 | 含义 | 你该做什么 |
|---|---|---|
| 401 | 密钥问题:未提供(missing_api_key)/格式不对(api_key_format_invalid)/已被重置或吊销(api_key_revoked)/库中不存在该密钥(invalid_api_key) |
到控制台复制最新完整明文密钥,并同步更新所有已配置该密钥的脚本与客户端 |
| 402 | 点数不足(insufficient_credits)或点数已过期(credits_expired) |
调 /quota(0 点)看余额与有效期 |
| 403 | 接口被停用(endpoint_disabled)/权限未开通/付费场次无订阅(subscription_required) |
换用功能相近的接口,或确认该场次的访问资格 |
| 404 | 资源不存在——绝大多数是 ID 错了 | 先用搜索接口确认正确 ID |
| 429 | 请求过于频繁(分钟限流)/同一任务正在处理中 | 按返回的等待时间重试 |
| 200 但数据不完整 | 不是错误:可能是完整包正在生成 | 见 4.6 的处理方式 |
二、五类高频问题详解
问题一 · 遇到 401 密钥问题怎么办?
401 全部是密钥本身的问题,服务端会把原因写进错误码,按错误码对号入座即可:
| 错误码 | 含义 | 怎么修 |
|---|---|---|
missing_api_key |
请求头里没有 X-API-Key |
补上请求头(密钥放 Header,不是 URL 参数、不是请求体) |
api_key_format_invalid |
密钥格式不对——最常见的是复制了带 **** 的掩码 |
到控制台复制完整明文(qxz_ 开头的 28 位),不要照着掩码自己拼 |
api_key_revoked |
这把密钥已被重置或吊销。在控制台点过「重置 Key」后,旧密钥会立即失效 | 改用控制台里当前那把新密钥,并把所有配置了旧密钥的地方一起换掉 |
invalid_api_key |
服务端不存在这把密钥(写错、少字符) | 重新复制一次完整明文密钥 |
最常见的场景是重置过密钥,但只改了其中一部分。同一个密钥往往同时存在于代码、环境变量和 AI 工具的客户端配置里,重置后只换一处,其余位置就会持续返回 api_key_revoked。正确做法是先把所有引用位置列出来一次性替换,替换完重启客户端。
# 用免费接口验证密钥是否生效(0 点,不影响余额)
curl -s 'https://www.qiuxiaoce.com/wp-json/abv2-creator/v1/quota'
-H 'X-API-Key: 你的完整密钥'
返回余额与有效期说明密钥正常;若仍返回 401,重新看一遍错误码——它已经把原因说清楚了。
问题二 · 遇到 402 点数不足或已过期怎么办?
这是最常见的报错。排查顺序:
- 先调免费接口看余额与有效期:
# 先查余额,再决定是否继续调用(0 点)
curl -s 'https://www.qiuxiaoce.com/wp-json/abv2-creator/v1/quota'
-H 'X-API-Key: YOUR_API_KEY_HERE'
- 余额够但报 402 → 多半是点数已过期,而不是不够;
- 余额充足、有效期也正常 → 确认这次调用的是不是高价接口(单场全景包 50 点、研报批发 1000 点)。
顺带一个习惯:脚本里在关键调用之前先读一次余额,余额低于阈值就直接跳过并提示,比跑到一半失败更省事。
问题三 · 遇到 403 权限问题怎么办?
403 有三种情况,注意区分:
| 情况 | 怎么判断 | 怎么办 |
|---|---|---|
| 接口被后台停用 | 同一接口昨天还能用,今天全部 403 | 换用功能相近的接口 |
| 付费场次未订阅 | 只有个别研报返回 403,且错误码是 subscription_required |
该场次需要对应访问资格,如实说明即可,不要绕过 |
| 字段权限未开通 | 错误信息指向具体权限 | 按提示在控制台确认 |
问题四 · 遇到 404 找不到资源怎么办?
绝大多数情况是 ID 错了。排查步骤:
# 搜球队,确认正确的 team_id
curl -s 'https://www.qiuxiaoce.com/wp-json/abv2-creator/v1/teams?q=阿森纳'
-H 'X-API-Key: YOUR_API_KEY_HERE'
# 搜球员,确认正确的 player_id
curl -s 'https://www.qiuxiaoce.com/wp-json/abv2-creator/v1/players?q=萨卡'
-H 'X-API-Key: YOUR_API_KEY_HERE'
搜索返回多个候选时,不要直接拿第一条继续用。同名不同国的情况很常见(例如「奥林匹亚」在希腊、洪都拉斯、巴拉圭各有球队),带 U21 / 女足 / 预备队后缀的也不是你要的一线队。正确做法是核对返回里的国家、是否国家队、别名等字段,仍不唯一时列出来让人确认。
还有两种情况也常见:① 联赛赛季口径不对(不确定时先调赛季列表);② 比赛还没入库(未来太远或数据源未覆盖)。
问题五 · 遇到 429 请求过于频繁怎么办?
限制是每分钟 30 次请求。正确的处理方式不是加大重试频率,而是:
import time
for fid in fixture_ids:
data = client.get(f"/fixtures/{fid}")
time.sleep(1.2) # 保持秒级间隔,天然不会触发限流
另外两种 429 长得很像但含义不同:同一任务正在处理中(重复提交同一个请求时出现,稍等再试)、下载过于频繁(技能包下载接口)。它们的共同点都是「等一下就好」,不是权限或配置问题。
三、60 秒去重怎么用才省点?
同一个密钥 + 同一个接口 + 同一个参数,60 秒内重复调用不重复扣点。调试时可以放心重复请求。
# 连续调用两次,第二次会命中去重(看响应头 X-Dedup-Hit)
curl -s -D - 'https://www.qiuxiaoce.com/wp-json/abv2-creator/v1/fixtures/1557403'
-H 'X-API-Key: YOUR_API_KEY_HERE' | grep -i 'x-dedup-hit'
但要注意它是按参数指纹判定的:参数变一个字就是一次新调用。所以「把日期从 16 号改成 17 号」不会命中去重,这符合预期。
四、排障 Checklist
- 余额和有效期查过了吗?(
/quota,0 点) - URL 拼对了吗?(未知路由会按 2 点计费,拼错既报错又扣点)
- ID 是搜索确认过的,还是猜的?
- 是不是调用了高价接口却以为很便宜?
- 循环调用里加了间隔吗?
- 返回 200 但数据不完整——确认过是不是「完整包生成中」吗?
五、遇到问题怎么求助
按上面的表排查后仍未解决,可以在 8.5 联系我们 反馈。反馈时请提供:
- 调用的完整 URL(请把密钥脱敏);
- 返回的状态码与响应体;
- 一个可复现的最简示例(能稳定重现的最小请求)。
下一步该看什么
- 计费规则与省钱 → 4.2 计费与省钱
- 把接口交给 AI 自动调用 → 5.1 一键挂载 Skill
- 自己建一套系统 → 7.11 自建系统架构
足球赛事前瞻 | AI 智能分析 | 足球数据解读 - 球小策