API 错误码 常见错误与排查思路

错误响应格式

Bot API 调用失败时，响应体的 ok 字段为 false，并包含 error 对象：

{
  "ok": false,
  "error": {
    "code": 400,
    "message": "参数错误"
  }
}

开发者应该检查 ok 字段来判断调用是否成功，而不是只依赖 HTTP 状态码——成功的 API 调用 HTTP 状态码可能是 200，但业务层面可能返回 ok: false。

HTTP 状态码 vs 业务错误码

关键： HTTP 状态码只是传输层的判断，业务成败必须看响应体里的 ok 字段和 error 对象。

常见业务错误码

以下错误码来自 Fanbook 开发者文档的公开信息，实际以官方最新文档为准。

注意： 以上为根据公开文档整理的常见错误码，完整列表请以官方开发者平台文档为准。

典型错误场景排查

场景一：调用接口返回「权限不足」

可能原因：

1. BOT 没有在目标服务器里
2. BOT 在服务器里但没有分配角色
3. BOT 的角色没有对应权限（如 SEND_MESSAGES）
4. 目标频道有频道级权限覆盖，BOT 被排除在外

排查步骤：

1. 确认 BOT 已被添加到服务器
2. 给 BOT 分配角色，角色里勾选需要的权限
3. 检查目标频道的频道级权限设置
4. 用 /getMe 确认 BOT 身份正确

场景二：调用接口返回「参数错误」

可能原因：

1. 参数名拼错（如把 guild_id 写成 guildId）
2. 参数类型错误（如传字符串给 Integer 类型字段）
3. 缺少必填参数
4. 消息体格式不对（应该是 JSON 却用了 x-www-form-urlencoded）

排查步骤：

1. 对照官方文档的参数列表逐个检查
2. 打印请求体的原始 JSON，确认格式正确
3. 检查 Content-Type 是否设为 application/json

场景三：消息发送后成员看不到

可能原因：

1. 频道有频道级权限覆盖，BOT 的消息被隐藏
2. 成员的客户端有问题
3. 消息实际发送成功但在客户端渲染延迟

排查步骤：

1. 检查 Bot API 响应的 ok 字段——是 true 还是 false
2. 用 /channel/messages 拉取频道消息列表，看 BOT 发的消息是否在里面
3. 如果消息在 API 返回中存在但成员看不到，是客户端问题

场景四：频繁触发限流

可能原因：

1. 调用频率太高（每秒发起多次请求）
2. 长轮询间隔太短
3. 循环中未加等待直接调用

建议处理：

import time

# 在循环调用中添加间隔
for item in items:
    api_call(item)
    time.sleep(0.5)  # 每次调用后等待

如果业务需要较高频率，考虑：

• 用 WebSocket 替代长轮询
• 批量调用（如果 API 支持）
• 联系 Fanbook 官方申请更高调用额度

场景五：Bot Token 调用任何接口都失败

可能原因：

1. Token 拼错（复制时多了或少了字符）
2. Token 被重置过（旧 Token 已失效）
3. Token 泄露后被官方吊销

排查步骤：

1. 检查 Token 字符串是否与机器人管理后台显示的完全一致
2. 如果无法确认，直接重置 Token 并更新代码

错误处理最佳实践

统一错误处理函数

def call_api(endpoint, params=None):
    url = f"{BASE}/bot/{BOT_TOKEN}/{endpoint}"
    resp = requests.post(url, json=params or {})
    data = resp.json()

    if not data.get("ok"):
        error = data.get("error", {})
        code = error.get("code", "unknown")
        msg = error.get("message", "未知错误")
        print(f"[API错误] {endpoint}: code={code}, msg={msg}")

        # 处理特定错误码
        if code in (401, 403):
            # 权限问题，可能需要日志记录 + 报警
            pass
        elif code in (6, 7, 429):
            # 限流，等待后重试
            time.sleep(2)
            return call_api(endpoint, params)  # 递归重试（注意设置最大次数）
        elif code == 500:
            # 服务器错误，稍后重试
            time.sleep(5)
            return call_api(endpoint, params)

        return None

    return data["result"]

记录错误日志

把每次 API 调用的失败详情（端点、参数、错误码、错误消息、时间戳）记录到日志里，方便后续排查问题。

幂等重试

对于非破坏性的操作（如查信息、发消息），可以在遇到限流或服务器错误时自动重试 1~2 次。但对于破坏性操作（如踢人、删除消息），不要自动重试——重复执行可能造成意外后果。