4.8 错误码与排障手册：402 / 403 / 404 / 429 全解

遇到报错不要慌，对照这张表定位即可。

一、错误码速查表#

二、四类高频问题详解#

问题一：402 点数不足#

这是最常见的报错。检查顺序：

1. 调用 /quota（0 点，免费）查看当前余额；
2. 确认密钥是否已过期；
3. 确认调用的是否为高价接口（如 match-pack 50 点）。

# 先查余额，再决定是否继续调用
curl -s 'https://www.qiuxiaoce.com/wp-json/abv2-creator/v1/quota' 
  -H 'X-API-Key: YOUR_API_KEY_HERE'

问题二：403 接口被拦截#

如果返回 403 且提示权限相关，可能是两种情况：

• 该接口在后台被停用 → 换用功能相近的接口；
• 免费接口的 IP 限流触发 → 免费接口有每分钟调用上限，等待或使用付费密钥。

问题三：404 找不到资源#

99% 的情况是 ID 错了。排查步骤：

1. 先用搜索接口确认正确 ID：

# 搜球队
curl -s 'https://www.qiuxiaoce.com/wp-json/abv2-creator/v1/teams?q=阿森纳' 
  -H 'X-API-Key: YOUR_API_KEY_HERE'

# 搜球员
curl -s 'https://www.qiuxiaoce.com/wp-json/abv2-creator/v1/players?q=萨卡' 
  -H 'X-API-Key: YOUR_API_KEY_HERE'

2. 用搜到的 ID 重新调用详情接口；
3. 如果 ID 确认正确仍返回 404，说明该资源尚未收录。

问题四：429 请求过于频繁#

降低调用频率，加入请求间隔：

import time
for fid in fixture_ids:
    data = client.get(f'/fixtures/{fid}')
    time.sleep(1.2)  # 建议秒级间隔

三、利用 60 秒去重规避重复扣点#

调试阶段反复请求同一接口是不会重复扣点的：

# 连续调用两次，第二次会命中去重
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'

如果返回 X-Dedup-Hit: 1，说明本次未扣点。

四、排障 Checklist#

五、遇到问题怎么求助#

如果按上面的表排查后仍然无法解决，可以通过 8.5 联系我们 反馈。反馈时请提供：

• 调用的完整 URL（请把密钥脱敏）；
• 返回的状态码与响应体；
• 一个可复现的最简示例。

下一步该看什么#

• 把接口交给 AI 自动调用 → 5.1 挂载 Skill
• 自己建一套系统 → 7.11 自建系统架构