凡是发布过 Discord 机器人的人都遇到过这种情况：平常的一个周二，突然到处都是 increased api errors，你的一半命令都失败了。谷歌趋势在 2026 年年中把这个短语列为“爆发式”搜索词；它出现得足够频繁，以至于终端用户会直接搜索它。下面介绍如何平稳度过这类情况，以及 Noxyr 服务器 API 从这些经验中借鉴了什么。

A request gets a 429, waits out a countdown, then retries and succeeds with a 200. Server 429 200 3 2 1 Retry-After

Discord API 最主要的三种故障模式

  • 全局宕机 / 部分宕机：可在 discordstatus.com 上看到。症状：任何请求都可能失败，网关可能断开，延迟全面飙升。
  • 429 Too Many Requests：你超过了某个桶的限制。Discord 会返回 Retry-After 响应头，准确告诉你需要等待多长时间。
  • 网关会话无效：你的 WebSocket 会话已过期。使用恢复令牌重新连接；如果失败，就重新进行完整的 identify。

为故障而设计，而不是为顺境而设计

  • 遵守 Retry-After。不要按照自己的定时器重试。按 Discord 告诉你的确切时长等待，然后只重试一次。无视 429 猛烈请求的机器人会被封禁。
  • 带抖动的指数退避。遇到 5xx 错误时，等待 1 秒、2 秒、4 秒、8 秒，再加上一个小的随机偏移，这样一批同时重启的实例就不会一拥而上。
  • 对非关键调用进行熔断。如果你的机器人每周发布一次摘要，而 Discord API 性能下降，就跳过这一轮，而不是雪上加霜。摘要可以等，宕机却不能等。
  • 缓存所有非实时数据。服务器名称、频道列表、身份组 ID，都缓存在本地。宕机期间，缓存数据能让你继续提供服务。
  • 展示状态。如果你的机器人命令因 Discord 宕机而失败，请告诉用户。一句“Discord 目前出现问题”，胜过无声的超时。

Noxyr 服务器 API 如何应用这些经验

Noxyr 服务器 API 并不是 Discord API，它读取的是自己的数据库，但同样的原则依然适用，并影响了它的设计：

  • 可预测的错误：每个失败都以带有稳定 error 代码的 JSON 形式返回。没有 HTML，也没有格式不一的内容。
  • 速率限制响应头：使用标准化的 RateLimit-* 响应头，让客户端在触发 429 之前就主动退避。
  • 优雅降级：当底层的 Discord 数据获取失败时，/api/v1/server 端点会回退到缓存的服务器数据。
  • 不会级联失败：每个端点各自独立失败。Discord 宕机不会破坏你的工单分析端点，因为它读取的是 Mongo，而不是 Discord。
  • 即时紧急开关：禁用某个密钥或权限范围会在下一次请求时立即生效，无需重启。

Discord 出现异常时的应对手册

  • 1. 先查看 discordstatus.com，是不是只有你遇到问题？
  • 2. 查看你自己的错误日志：429、5xx、网关断开。
  • 3. 如果是 Discord 的问题：暂停非关键写入，遵守 Retry-After，等待恢复。
  • 4. 如果是你的问题：检查最近的部署、缓存失效以及新功能。
  • 5. 及时沟通。在支持频道中发一条简短而诚实的说明，可以避免 100 条重复的报告。

关于 API 层的更多内容：Noxyr 服务器 API、Discord API 与 Noxyr API 对比、API 设计原则。