生成器常见错误排错

生成器只是 Steam 公开 API 上很薄的一层，所以它返回的错误基本上是上游错误的直译。这篇文章汇总了最常见的几种、它们的真实含义，以及对应的处理方法。

1. "A valid numeric App ID is required"

出现频率最高的错误。三种常见原因：

• 你在搜索框里输入了名字而不是数字，然后在下拉建议还没来得及解析时就点了 Generate。下拉在失焦时会收起，于是提交了一个空的 App ID。
• 输入的 App ID 有错（多/少一位数字、字母、前导零、空格）。
• 字段是空的——快速连按回车会绕过空值校验。

修法：只输入或粘贴数字。不要字母、不要前导零、不要空格。

2. "App <id> was not found in the Steam store"

App ID 格式正确，但 Steam 的 appdetails 接口没有返回记录。几乎一定是以下三种之一：

• 数字错了。SteamDB 是最快的核对方式。
• 这个 ID 的应用只在其他区域（非 cc=us）售卖。部分应用被锁在单一商店。目前我们只支持部分区域，先在浏览器里用同 ID 打开本地商店 URL 确认应用确实存在。
• 这个 ID 已被 Steam 下架。SteamDB 仍保留记录，但 appdetails 不再返回。

修法：去 SteamDB 核对 ID。如果 SteamDB 上有但生成器仍然拒绝，来 Discord 留言，我们会加缺失的区域。

3. "Steam search failed (429)"

触发了 Steam 的限流。生成器对每个 IP 在搜索端强制 300 ms 间隔、生成端 1.5 s 间隔；Steam 上游也会限流。遇到这个就等几秒再试——限流是按 IP 而非账号，很快会重置。

修法：等 5–10 秒重试。如果你是脚本调用 API，去 Discord 看限流响应头，可以优雅退避。

4. "App ID is too long"

粘贴的位数超过 10 位。Steam App ID 是 32 位无符号整数（最大 4,294,967,295），但实际中没有超过 7 位的，多在 4–6 位。看到 "too long" 通常是粘贴了 URL 片段或 SteamDB 的 JSON。

修法：复制 ID 本身，不要复制 URL 或 JSON。

一种解决大多数问题的通用方法

所有支持消息里大约 80% 最后归结为"你输入的 App ID 错了，正确的应该是 X"。最常见的错误是从 SteamDB 抓错数字。SteamDB 页面会同时显示四个数字：App ID、package ID、depot ID、build ID。你要的是 App ID。其他三个是不同的东西。

如果分不清哪个是哪个，看 SteamDB 页面顶部的 store URL（store.steampowered.com/app/<APPID>/...）——那个就是。

如果错误信息不在上面

生成器是 TanStack Start 服务路由；完整错误信息会以 { "code": -1, "message": "..." } 返回。如果遇到上面没列过的消息，整条复制到 Discord，通常一小时内能定位。