Grok 首请求失败排查树

第一条请求报错时，最常见的三连动作是：换密钥、换模型、换 SDK。三样都换过，报错照旧，人开始怀疑网络。原因通常很朴素——失败是分层的，层没找对，换什么都白换。

这一节给一张分诊表：输入状态码与响应形态，输出「哪一层」和「第一步做什么」。它不追求穷举，只追求让你在三十秒内停止瞎试。

一、分层的第一判据不是状态码

先看 Content-Type，比先看状态码更划算：

• 返回 text/html：请求很可能根本没到推理端点。这是地址层问题。
• 返回 application/json：请求到了某个 JSON 接口，问题在协议层。

这条判别之所以要提前，是因为同样的 404 在两个层里含义完全不同。HTML 版 404 说的是「这个域名下没有 API，你打到了网页」；JSON 版 404 说的是「接口在，路径不对」。把两者混为一谈，就会一边改路径一边怀疑域名，来回拉锯。

补充一条实操经验：有些网关或代理会改写 Content-Type。所以响应体本身也是判据——正文以 < 开头，就当 HTML 处理。

二、分诊器

"""首请求失败分诊：输入状态码 / Content-Type / 响应体片段，输出层与第一步动作。"""


def triage(status: int, content_type: str, body: str = "") -> tuple:
    """返回 (层, 第一步动作, 是否重试)。重试只针对可安全重放的情形。"""
    ctype = (content_type or "").lower()

    # 地址层的判别优先于状态码：HTML 说明请求打到了网页，而不是 API
    if "text/html" in ctype or body.lstrip().startswith("<"):
        return ("地址层", "核对 base_url 的 hostname 与 path，先别动密钥", "否")

    if status == 401:
        return ("认证层", "打印环境变量名与读取时机，确认不是空值或占位符", "否")
    if status == 403:
        return ("权限层", "读响应体里的说明，到控制台核对团队权限与资源状态", "否")
    if status == 404:
        return ("路径层", "对照 API 参考核对路径与方法，别换模型", "否")
    if status in (400, 422):
        return ("请求体层", "先打印请求体原文，再逐字段对照名称与类型", "否")
    if status == 429:
        return ("限流层", "读 Retry-After，退避一次，同时记录本地请求速率", "是")
    if 500 <= status < 600:
        return ("服务端层", "有限次退避重试，并把响应里的请求标识留档", "是")
    return ("未分类", "把状态码、Content-Type 与响应体前 200 字留档", "否")


DEMO = [
    (404, "text/html; charset=utf-8", "<title>Not Found</title>"),
    (404, "application/json", '{"error": "path not found"}'),
    (401, "application/json", '{"error": "invalid api key"}'),
    (429, "application/json", '{"error": "rate limit"}'),
    (400, "application/json", '{"error": "unknown field"}'),
]

if __name__ == "__main__":
    print("| 输入 | 层 | 第一步动作 | 重试 |")
    print("| --- | --- | --- | --- |")
    for status, ctype, body in DEMO:
        layer, action, retry = triage(status, ctype, body)
        print(f"| {status} / {ctype.split(';')[0]} | {layer} | {action} | {retry} |")

注意第三个返回值。它比「这是什么错」更值钱：400 重试三次，只是把一次配置错误变成三倍告警，还可能顺手把你推近限流窗口。分诊器里明确写「否」，是为了让这段逻辑能在代码里被复用，而不是只贴在文档上。

三、状态码分层与重试判据

三点必须说清：

• 上表是本教程的排查分层，不是官方定义。官方页没有逐条定义这些状态码的语义，真实归因以响应体里的说明与控制台当前状态为准。把它当官方结论引用，是本节最容易被误用的地方。
• 403 值得单独查一处。官方账号 FAQ 说明了账号在 Grok 与 API 之间是共享的，但计费是分开的。这意味着「身份没问题却仍被拒」时，要核对的地方可能在控制台的团队与账单侧，而不是产品站。
• 429 只有在读到 Retry-After 时才有意义。没有这个响应头就退避，等于用猜的间隔去撞限流窗口，撞几次之后你会以为限流阈值比实际更小。

四、预期输出与异常分支

运行 __main__，五组样本应输出：

| 输入 | 层 | 第一步动作 | 重试 |
| --- | --- | --- | --- |
| 404 / text/html | 地址层 | 核对 base_url 的 hostname 与 path，先别动密钥 | 否 |
| 404 / application/json | 路径层 | 对照 API 参考核对路径与方法，别换模型 | 否 |
| 401 / application/json | 认证层 | 打印环境变量名与读取时机，确认不是空值或占位符 | 否 |
| 429 / application/json | 限流层 | 读 Retry-After，退避一次，同时记录本地请求速率 | 是 |
| 400 / application/json | 请求体层 | 先打印请求体原文，再逐字段对照名称与类型 | 否 |

前两行是本节的要点：同一个状态码，落在两个不同的层。真实排查里最常见的三类误判，恰好都源于没看这一行差别：

五、判据卡

这张卡的价值在于顺序。它不要求你记住六个状态码，只要求你在按下「换密钥」之前，先花十秒确认请求打到了哪里。

六、来源与核验

• 官方 Quickstart：https://docs.x.ai/developers/quickstart（核验日期 2026-11-04）。端点路径、首请求写法与认证头形态来自该页。
• 官方账号 FAQ：https://docs.x.ai/developers/faq/accounts（核验日期 2026-11-04，页面本次实测可达）。账号在 Grok 与 API 之间共享、计费分开管理的说明来自该页。
• 状态码语义以响应体说明与官方 API 参考为准；上表是本教程的排查分层，不是官方定义。完整重试策略见 10.1，本节只覆盖首请求阶段。

七、动手试

1. 把 DEMO 换成你真实遇到过的三组输入（脱敏），看分诊结果与你当时的动作是否一致。不一致的那一条，是谁错了？
2. 给 triage() 加一个参数 attempt（当前第几次尝试），让 429 在第三次之后返回「停止重试，改为告警」。想一想，这个上限该按次数定，还是按时间窗口定？
3. 如果团队只能记住一条规则，你会留「先看 Content-Type」还是「400 不重试」？写出你的理由，不超过 40 字。