🏠 总目录📚 本教程 03b · 接口的形状 ← →

AI全栈 / 03b

请求失败以后,客户端该不该重试?

资源、方法、状态码和错误细节一起决定接口的使用方式。

能把成功路径与失败后的下一步写进同一份接口约定。

对照状态码与重试

📑 本页目录(点开跳转)

03b · 接口的形状:资源怎么划、方法怎么选、状态码怎么返

HTTP 的“安全方法”和“可重试”要分开理解:幂等比较的是请求的预期效果,响应状态码可以不同。见 RFC 9110 §9.2.2。

⏱ 76 分钟 | ⭐ 第 11 章讲任务失败后怎么处理。本章补齐服务端怎样写出可判断的接口响应


🎯 一句话

状态码不是给人看的装饰,是你对客户端下的一道指令:这个错该不该重试、这个请求还要不要再发。 后面好几章都在读你返回的那个数字并据此行动,却没有一章讲你该怎么写它。


🧩 一、先把洞指出来:一条规则只有一半

第 11 章第五节立了一条判据,第 16 章的验收项就是照它写的:

先核对错误原因,再判断能否重发。输入有误先修输入,凭证失效先处理凭证。服务暂时故障可能恢复,但还要确认重发安全并控制预算。

第 4 章的重试白名单、第 12 章的项目约定「429 尽量带 Retry-After」,都建在同一件事上:对面返回的那个数字是可信的。

⚠️ 但到这一章为止,本板块的业务接口基本只有 POST /chat 一种形状(GET 只出现在查任务和健康检查上),而「该返哪个状态码」只被顺手提过几次(03 章的 422、11 章的 202、12 章的 429),没有一处讲判据。规则的消费端讲透了,生产端是空的。 而写错一个码,就是让对面做出错误的决定:

你写错的方向 对面会做什么 症状
「prompt 超长」返成 500 按白名单重试 3 次 本该 0.2 秒的确定性错误拖成 8 秒,⚠️ 日志里像上游在抖(04 章原话)
「上游 502」翻译成 400 一次就进死信 瞬时故障变成永久丢件,⚠️ 死信里躺着本该重试一次就好的活
「没权限」返成 401(该 403) 前端跳登录页 登录成功 → 又被踢回登录页 → 无限循环
摘要仍在排队,却用 201 承诺已经创建结果消息 立刻去拿结果 GET 那个地址得到 404,前端分不清是自己拿早了还是你搞砸了

⭐ 本章主判据:每个状态码都在回答两个问题 —— 这是谁的错?对面该不该再发一次? 别的判据(好不好看、REST 纯不纯)都排在这后面。

顺序是 先划资源 → 再选方法 → 最后定状态码;跳过前两步直接背状态码表,很多码根本没地方用。


🧱 二、资源怎么识别:名词不是动词

❌ POST /createConversation  ❌ POST /getMessages  ❌ POST /deleteMessage
✅ POST /conversations   ✅ DELETE /messages/{mid}   ✅ GET /conversations/{cid}/messages

⚠️ 这不是风格洁癖。 左边一列的共同点是方法全为 POST,于是所有中间层(反向代理、CDN、浏览器、日志、限流器、04 章那个重试器)看到的都是「一个不透明的 POST」——能不能缓存?重发安不安全?是读还是写?全推不出来。 你把信息藏进了 URL 字符串,而没有一个中间层会去读它。

⭐ URL 层级和第 6 章那两张表一一对应:/conversations/{cid}/messages 正是那章实测的热路径 WHERE conversation_id=? ORDER BY seq(建 (conversation_id, seq) 索引后 200 次查询 3.802 秒 → 0.0019 秒)。这不是巧合 —— 两者都在回答「这批数据按什么维度成批取出」。

⭐ 什么时候该单独建一个资源?判据:这件事有没有自己的生命周期 —— 需不需要被单独查询、单独重试、单独取消?

「总结这段文字」300 毫秒同步返回 → ❌ 没有中间状态,就是一次 POST;「总结这份 200 页 PDF」跑 3 分钟 → ✅ 有了 queued / running / done、有了查进度和取消,这三样一出现它就必须有自己的 id。⭐ 第二种就是第五节的引子:它同时是「一条消息」和「一个任务」,两种建模会打架。 ⚠️ 反方向的过度也真实存在 —— 别机械地给每张表配五个端点,判据同样是「有没有客户端真的要用」。


🤝 三、方法是承诺,不是规矩

选 GET 还是 POST 感觉像按规矩办事。实际上它是你向所有客户端和中间层公开的一份承诺,而它们真的照着行事,不问你一句。

方法 安全(语义上只读) 幂等(重发,终态一样) ⭐ 谁在依赖这个承诺
GET ✅ ✅ 浏览器预取、CDN 缓存、爬虫跟着链接走、网络抖动时自动重发
POST ❌ ❌ 不承诺安全或幂等;一般不自动重发。响应有条件可缓存,不能据此再次执行 POST
PUT ❌ ✅ 整体替换。同一份 body 重发,终态相同
PATCH ❌ ⚠️ 不保证 局部修改。给绝对值就幂等,给「计数 +1」就不是
DELETE ❌ ✅ 删两次预期终态都是「没了」;第二次返回 404 或 204 都可以,取决于接口契约

⭐ 幂等在本章只有一句话的分量:PUT / DELETE 约定重复请求的预期效果相同,POST 没有。 怎么让不幂等的 POST 也能安全重发(Idempotency-Key、ETag、条件请求)是下一章 03c 整章的事。

💀 最贵的一条:把会改状态的操作写成 GET(GET /messages/{mid}/delete)。它能跑、测试也过,然后 —— 阅读器和浏览器会预取(带这个链接的页面被打开一遍,东西就没了)、CDN 会缓存住那个「成功」(下次点击根本没到你的服务器)、重试器会自动重发、⚠️ 参数还会被各层记进日志(和第 8 章那行 GET /api/docs?tenant=globex 是同一个家族的问题)。

把查询写成 POST /search 会失去通用 GET 缓存和可分享链接的便利,但并非只有「查询体太大」才合法。选择由方法语义、数据敏感性和接口契约决定;POST 本身不提供加密,HTTPS 才保护传输。

🚦 AI 应用的一个现实:生成天然不幂等。 第 2 章四件难事的最后一条就是「同样输入不同输出」—— 同一段 prompt 发两次会得到两条回复、两笔账。⭐ 所以发消息就该是 POST,用承诺幂等的 PUT 去包装它是在对客户端撒谎;正确做法是承认它不幂等,再单独加一层保护(03c,也正是 11 章第四节结尾「更稳的是让客户端传 Idempotency-Key 头」指向的地方)。

# 本例选择两次都返回 204;幂等本身不要求状态码相同
from fastapi import FastAPI
from fastapi.testclient import TestClient

app = FastAPI()
CONV = {"c1": {"title": "报销问题", "archived": False}}


@app.patch("/conversations/{cid}")                     # 局部修改:给哪个字段改哪个
def patch_conv(cid: str, body: dict):
    CONV[cid].update(body)      # ⚠️ body 若是"计数 +1"这类相对操作,这个接口就不幂等
    return CONV[cid]


@app.delete("/conversations/{cid}", status_code=204)   # ⭐ 幂等:删两次,终态都是"没了"
def del_conv(cid: str):
    CONV.pop(cid, None)         # 本例选择第二次也返 204;幂等不要求两次响应码相同
    return None


c = TestClient(app)
print("PATCH    ", c.patch("/conversations/c1", json={"title": "报销流程"}).json())
print("DELETE x2", [c.delete("/conversations/c1").status_code for _ in range(2)])

实跑:PATCH 只改了给的那个字段({'title': '报销流程', 'archived': False}),⭐ DELETE 连发两次都是 [204, 204] —— 第二次没有报 404。这是本例选用的响应契约;第二次返回 404 仍然符合幂等,因为预期终态相同。


可选深入:方法、字段与重定向,分别告诉谁做什么

GET 请求读取表示,POST 请目标资源处理提交内容。参数放 URL 还是 body 不是两者的定义;GET 的请求内容没有通用定义的语义,别依赖中间层理解它。安全方法允许日志等附带效果,不等于服务器内存一个字也不变。

POST 响应在显式声明新鲜度、Content-Location 等于目标 URI 等条件满足时可缓存,并可用于后续 GET/HEAD;不能用缓存响应代替再次执行 POST。实际缓存还须支持该方法并满足授权和缓存指令约束;多数通用缓存只实现 GET/HEAD。

同一次 /api/chat 交互中的常见字段
字段及方向解决的问题
请求 Accept;两向 Content-Type前者说能接受哪种表示,后者说本条消息内容是什么。请求 JSON、响应事件流是两次不同声明。
请求 Authorization;响应 WWW-Authenticate提交凭据与返回认证挑战;错误信息不能回显 token。
请求 Host / HTTP/2 的 :authority标明目标主机,供入口路由;不是可信客户端身份。
两向 Cache-Control;响应 Age请求指令约束缓存使用;响应指令定义可存储性/新鲜度。Age 是生成或验证后的估计秒数,不是剩余寿命。
响应 ETag / Last-Modified提供验证器;请求的 If-None-Match / If-Modified-Since 用它们问「是否改变」。验证与直接复用新鲜缓存是两步不同的判断;详细条件请求见 03c。

重定向让客户端另发请求;内部转发由服务器在内部继续处理。例如响应 303 + Location: /jobs/j1 后,客户端按该规则发 GET 取任务;307/308 保留方法和请求内容。301/302 为兼容历史可把 POST 改为 GET,不能拿来保证保留请求体。跟随策略还受客户端和跨源安全规则限制。

反向代理把 /api/chat 转给内部 app,不要求浏览器再请求一次,地址栏通常不变;客户端看不到内部路由不等于没有额外上游请求。30x 是响应,内部转发是服务器动作,二者不要混称。

依据:RFC 9110 方法与重定向、RFC 9111 缓存字段、RFC 6585 的 429。这里只补接口判据,不展开 03c 的实现。

🚦 四、状态码:判据是「谁的错、要不要重试」

状态码先说明处理结果,重试还要单独判断。4xx 表示请求侧错误,5xx 表示服务器未能完成请求;这不是「4xx 永不重试、5xx 一定重试」的开关。先看具体错误能否恢复,再看重发是否安全,最后设次数和时间预算。生成请求超时,也可能已经生成并扣费。

成功侧 意思 用在哪
200 当前请求处理成功 例如成功读取任务状态,任务本身可能仍在运行
201 Created ⭐ 新资源已经存在了 创建会话后,本例用 Location 给出它的地址
202 Accepted ⭐ 收到了,但还没答应你它会成功 接受生成请求,本例提供任务地址供查询
204 No Content 成了,没有 body DELETE、纯状态切换。⚠️ 前端别去 JSON.parse("")
4xx 它在回答的问题 典型场景
400 我根本没读懂你的请求 body 不是合法 JSON、必需的头缺了
401 我不知道你是谁 没带 token / 过期。⭐ 要带 WWW-Authenticate
403 读懂请求,但拒绝执行 只读 token 想写、免费版调付费模型
404 它不存在(或:我不打算告诉你它存不存在) id 写错、⭐ 跨租户访问
409 请求没问题,是资源现在的状态不允许 对已经 done 的 job 发取消
422 我读懂了,但内容不合法 max_tokens=99999、空 message(03 章那行)
429 你太快了 / 额度不够 协议允许带 Retry-After,并非必带;本项目尽量提供(12 章讲计算)

⭐ 401 vs 403 一句话:401 先按认证挑战处理缺失或无效凭证;403 表示当前请求被拒,不应自动以同凭证原样重试。 新凭证或权限/策略改变可能恢复请求,403 也可能与凭证无关,不能一律跳登录页(RFC 9110 §15.5.4)。 ⚠️ 混用的症状很典型:用户登录成功、被跳回来、又是 403、又跳登录 —— 无限循环,而日志里全是成功的登录。 ⭐ 400 vs 422 就没那么要紧(FastAPI 里 Pydantic 校验失败默认 422,两者在重试语义上同一档),写出来只是为了让你知道哪些地方不随便。

⭐ 409:先解决状态冲突,再决定是否重试

409 表示请求与资源当前状态冲突。对已完成的 job 发取消,等一会儿也不会重新变成可取消;应查询状态并结束这次动作。若接口明确把短暂锁冲突映射为 409,才可能在有上限的退避后重试;版本冲突往往要先取新版本并合并,不能原样盲发。

⭐ 补全后的分诊表 —— 这就是 11 章那条规则缺的另一半:

服务端返回 谁的错 客户端该做 队列里
400 / 422 你 改请求再发 死信
401 你(凭证) 去登录,拿新凭证再发 死信(后台任务没法「去登录」)
403 你(权限) 不以同凭证原样自动重试;先核对权限/策略 死信
404 你(大概) 别再发了 死信。⚠️ 例外:刚创建就查会撞时序,退避重试一两次
⭐ 409 资源状态冲突 查状态;按错误类型解决冲突 可恢复且重发安全才有限重试;已完成任务不再取消
429 你太快 / 额度 有有效 Retry-After 则等待;缺省按本地退避策略,不立即连发 确认可恢复及重发安全后,在预算内重试
5xx / 超时 我 判断是否瞬时故障,核对是否已执行 幂等或有可靠去重保护,且预算允许才退避

⭐ 跨租户到底返 404 还是 403?16 章那条验收项写的是「用 A 的 token 请求 B 的资源 id → 404 / 403」,两个都算过、没说选哪个。判据在这儿:

⭐ 403 承认了「这个 id 存在」。 id 一旦可枚举,它就成了探测接口 —— 拿一个合法账号就能数出你有多少客户、哪些 id 是活的。 判据:如果「存在与否」本身是敏感的,就返 404。 ⚠️ 代价是你自己排查时也分不清「真没有」和「没权限」,⭐ 解法是对外统一 404、日志里记真实原因和 trace_id(03 章那条原则)。

# 五个 4xx 各自在回答哪个问题:判据不是"错了",是"谁的错、要不要重试"
from fastapi import FastAPI, Header, HTTPException
from fastapi.testclient import TestClient
from pydantic import BaseModel, Field

app = FastAPI()
TOKENS = {"t_u1": ("u1", True), "t_ro": ("u1", False)}   # token -> (谁, 能不能写)
JOBS = {"j_run": ("u1", "running"), "j_done": ("u1", "done"), "j_other": ("u2", "running")}


class CancelIn(BaseModel):
    reason: str = Field(min_length=1, max_length=200)   # ⭐ 空 reason 进业务之前就被 422 挡掉


@app.post("/jobs/{jid}/cancellation")
def cancel(jid: str, body: CancelIn, authorization: str = Header(default="")):
    who = TOKENS.get(authorization[7:]) if authorization.startswith("Bearer ") else None
    if who is None:                                     # ⭐ 401 = 不知道你是谁,换个凭证可能就行
        raise HTTPException(401, "unauthenticated", headers={"WWW-Authenticate": "Bearer"})
    me, can_write = who
    owner, status = JOBS.get(jid, (None, None))
    if owner != me:                                     # ⭐ 别人的也返 404:403 会承认它存在
        raise HTTPException(404, "no such job")
    if not can_write:                                   # ⭐ 403 = 知道你是谁但不许,别跳登录页
        raise HTTPException(403, "read-only token")
    if status != "running":                             # ⭐ 409 = 资源【现在的状态】不允许
        raise HTTPException(409, "job already " + status)
    return {"status": "cancelling"}


c, ok = TestClient(app), {"reason": "点错了"}
for tok, jid, body in [("", "j_run", ok), ("t_u1", "j_run", {"reason": ""}),
                       ("t_u1", "j_other", ok), ("t_ro", "j_run", ok),
                       ("t_u1", "j_done", ok), ("t_u1", "j_run", ok)]:
    h = {"Authorization": "Bearer " + tok} if tok else {}
    print(c.post(f"/jobs/{jid}/cancellation", json=body, headers=h).status_code, end=" ")

六个用例依次是「没带 token / reason 空串 / 别人的 job / 只读 token / 已经 done 了 / 正常」,实跑输出 401 422 404 403 409 200。⭐ 判断顺序本身也是设计:先认人(401)→ 判归属(404)→ 判权限(403)→ 判状态(409)。⚠️ 颠倒会漏信息 —— 先判状态的话,别人靠「这个 id 返 409 而不是 404」就能推断出它存在且正在运行。

🧯 流式请求的分界是响应头已经发出。输入有误且响应还没开始时,可以直接返回 4xx。已经以 200 开始流式响应后,后续失败用正文事件报告,或由客户端根据提前断流判断。见第 05 章。


🔍 五、一次对话既是资源,又是长任务

用户打开空白会话,输入「总结这份年报」。界面需要分别回答三个问题。会话是否已经创建?后台任务是否已经接收?摘要是否已经生成?会话、任务和结果消息分别有自己的地址,客户端才能查到对应状态。

这里复用第 06 章的会话与消息关系,并把第 11 章的任务查询落实到接口。用户消息可以先出现,任务生成的助手消息稍后补上。接口契约(API Contract)规定每一步发什么、收到什么,以及客户端接下来可以做什么。

本次操作响应说明客户端接下来做什么
同步创建会话或消息201,本例用 Location 标明新资源读取已创建的资源
逐段展示生成内容200,响应正文以事件流传递读事件判断结果,见第 05 章
接收稍后处理的生成请求202,本例给出任务查询地址查任务状态,成功后再取结果

跟完一次「总结这份年报」

① 建会话发 POST /conversations,收到 201 和会话地址 /conversations/c1。
② 提交消息发 POST /conversations/c1/messages,收到 202、用户消息序号和任务地址 /jobs/j1。
③ 查任务发 GET /jobs/j1。收到 200 后读正文中的 status。
④ 取结果status 为 done 时,按 result_url 读取那条助手消息。

第一次提交的 JSON 是 {"content":"总结这份年报"}。202 的正文给出 job_id、status、status_url 和 user_message_seq。用户消息序号让界面能标记刚提交的那句话。本例从 0 编号,第一条用户消息的序号是 0。第 06 章示例从 1 开始,序号起点由各接口约定。status_url 与本例的 Location 都指向同一个任务。查询返回 200 时,客户端已经读到了任务记录,仍需看生成有没有完成。

queued · 已接收

任务还没生成结果。页面保留用户消息,按计划再查。

done · 已生成

本例返回 result_url 指向助手消息。先取到消息,再展示摘要。

failed · 已结束

页面显示失败,停止轮询。保留用户消息,根据 failure_code 决定下一步。

再分清三个拒绝。 空白消息得到 422 / invalid_input,改好输入再发。取消已经完成的任务得到 409 / job_not_cancellable,查原任务并结束取消流程。服务暂时无法接收新任务时,本例在接收前返回 503 / queue_unavailable,界面提示暂不可用。是否重发还要核对有没有执行过、重发是否安全。503 本身不证明其他接口没执行,下一章会讲怎样处理结果不明的重试。

用 Python 3.11+ 运行以下练习。安装方式沿用第 03 章,本例用到 FastAPI 和 HTTPX。保存为 interface_demo.py 后运行 python interface_demo.py。请求在进程内发送,内存字典只记录本次练习数据。finish_job() 由测试显式调用,模拟后台进程推进任务,查询路由只读。真实队列、持久化、并发和权限由对应章节继续讲。

import asyncio
from uuid import uuid4

from fastapi import FastAPI, Response
from fastapi.responses import JSONResponse
from httpx import ASGITransport, AsyncClient

app = FastAPI()
app.state.accepting = True
CONVERSATIONS = {}
JOBS = {}


def problem(status, code, message):
    return JSONResponse(status_code=status, content={"error": {
        "code": code, "message": message, "trace_id": uuid4().hex,
    }})


@app.post("/conversations", status_code=201)
def create_conversation(response: Response):
    cid = f"c{len(CONVERSATIONS) + 1}"
    CONVERSATIONS[cid] = []
    response.headers["Location"] = f"/conversations/{cid}"
    return {"id": cid}


@app.get("/conversations/{cid}")
def get_conversation(cid: str):
    if cid not in CONVERSATIONS:
        return problem(404, "conversation_not_found", "找不到会话")
    return {"id": cid}


@app.post("/conversations/{cid}/messages", status_code=202)
def post_message(cid: str, body: dict, response: Response):
    messages = CONVERSATIONS.get(cid)
    if messages is None:
        return problem(404, "conversation_not_found", "找不到会话")
    content = body.get("content")
    if not isinstance(content, str) or not content.strip():
        return problem(422, "invalid_input", "请填写消息")
    if not app.state.accepting:
        return problem(503, "queue_unavailable", "暂时不能接收任务")
    seq = len(messages)
    messages.append({"seq": seq, "role": "user", "content": content})
    jid = f"j{len(JOBS) + 1}"
    JOBS[jid] = {"cid": cid, "status": "queued"}
    url = f"/jobs/{jid}"
    response.headers["Location"] = url
    return {"job_id": jid, "status": "queued", "status_url": url,
            "user_message_seq": seq}


@app.get("/jobs/{jid}")
def get_job(jid: str):
    job = JOBS.get(jid)
    if job is None:
        return problem(404, "job_not_found", "找不到任务")
    return job  # 查询只读取已记录的状态


@app.get("/conversations/{cid}/messages/{seq}")
def get_message(cid: str, seq: int):
    messages = CONVERSATIONS.get(cid, [])
    if not 0 <= seq < len(messages):
        return problem(404, "message_not_found", "找不到消息")
    return messages[seq]


@app.post("/jobs/{jid}/cancellation")
def cancel_job(jid: str):
    job = JOBS.get(jid)
    if job is None:
        return problem(404, "job_not_found", "找不到任务")
    if job["status"] != "queued":
        return problem(409, "job_not_cancellable", "请查询任务当前状态")
    job["status"] = "cancelled"
    return {"status": "cancelled"}


def finish_job(jid, success):
    # 测试显式调用的假 worker,不是 HTTP 路由。
    job = JOBS[jid]
    assert job["status"] == "queued"
    if not success:
        job.update(status="failed", failure_code="generation_failed")
        return
    cid = job["cid"]
    messages = CONVERSATIONS[cid]
    seq = len(messages)
    messages.append({"seq": seq, "role": "assistant", "content": "年报摘要示例"})
    job.update(status="done", result_url=f"/conversations/{cid}/messages/{seq}")


async def verify():
    transport = ASGITransport(app=app)
    async with AsyncClient(transport=transport, base_url="http://testserver") as client:
        created = await client.post("/conversations")
        assert created.status_code == 201
        location = created.headers["Location"]
        assert location == "/conversations/c1"
        conversation = await client.get(location)
        assert conversation.status_code == 200 and conversation.json() == {"id": "c1"}

        endpoint = location + "/messages"
        accepted = await client.post(endpoint, json={"content": "总结这份年报"})
        assert accepted.status_code == 202
        ticket = accepted.json()
        status_url = ticket["status_url"]
        assert status_url == accepted.headers["Location"] == "/jobs/j1"
        assert ticket["user_message_seq"] == 0
        for _ in range(2):
            pending = await client.get(status_url)
            assert pending.status_code == 200 and pending.json()["status"] == "queued"
            assert "result_url" not in pending.json()

        finish_job(ticket["job_id"], success=True)
        completed = await client.get(status_url)
        assert completed.status_code == 200 and completed.json()["status"] == "done"
        result = await client.get(completed.json()["result_url"])
        assert result.status_code == 200 and result.json() == {
            "seq": 1, "role": "assistant", "content": "年报摘要示例",
        }

        conflict = await client.post(status_url + "/cancellation")
        assert conflict.status_code == 409
        assert conflict.json()["error"]["code"] == "job_not_cancellable"
        assert (await client.get(status_url)).json() == completed.json()

        sizes = (len(CONVERSATIONS["c1"]), len(JOBS))
        invalid = await client.post(endpoint, json={"content": " "})
        assert invalid.status_code == 422 and invalid.json()["error"]["code"] == "invalid_input"
        app.state.accepting = False
        busy = await client.post(endpoint, json={"content": "总结这份年报"})
        assert busy.status_code == 503 and busy.json()["error"]["code"] == "queue_unavailable"
        assert (len(CONVERSATIONS["c1"]), len(JOBS)) == sizes

        app.state.accepting = True
        accepted_again = await client.post(endpoint, json={"content": "总结另一份年报"})
        assert accepted_again.status_code == 202
        ticket_again = accepted_again.json()
        finish_job(ticket_again["job_id"], success=False)
        failed = await client.get(ticket_again["status_url"])
        assert failed.status_code == 200 and failed.json()["status"] == "failed"
        assert failed.json()["failure_code"] == "generation_failed"
        assert "result_url" not in failed.json()

    print("201 → 202 → 200 queued → 200 done → 200 result")
    print("409 / 422 / 503 → 200 failed")


if __name__ == "__main__":
    asyncio.run(verify())

先核对两次轮询都是 200 / queued,也都没有结果地址。测试推进任务后才读到 done,随后用结果地址取到第 1 条助手消息。另一次任务虽然同样以 202 接收,查询到的终态却是 200 / failed。这时 200 说明状态读到了,生成失败由任务正文说明。代码还检查了 422 和 503 都没有新建消息或任务,以及 409 保留已完成的结果。

本接口约定用 Location 和 status_url 指向查询入口。HTTP 的 202 表示已接受、处理尚未完成,建议在响应中描述状态并指向状态监视器。201 则表示创建已经完成,主要资源由 Location 或请求目标标明。RFC 9110 §15.3.2–15.3.3。


📋 六、错误响应:状态码定大方向,code 定细节

第 3 章已经把形状定死了(code 机器码 + message 人话 + trace_id),这里只补两条关系:① ⭐ 状态码全世界共用,code 是你自己的词表 —— prompt_too_long、quota_exhausted 不该编进状态码,⚠️ 更别自定义 4xx 码(比如返 460),中间层不认识它,一律当普通 4xx 处理。② ⭐ 同一个 code 必须永远对应同一个状态码;把这个映射写成一张表放进代码,别散在各个 raise 里。

场景 状态码 code 队列里
prompt 超长 422 prompt_too_long 死信
内容被安全策略拒绝 422 content_blocked 死信(⚠️ 这是判断结果不是故障,04 章原话)
用户发太快 429 + Retry-After rate_limited 重试
⭐ 你的上游额度不够 503,恢复时间可估时可带 Retry-After upstream_unavailable 先判断故障能否恢复、重发是否安全,再在预算内等待或重试
job 已完成,不能取消 409 job_not_cancellable ⚠️ 不重试,也不算失败

⭐ 倒数第二行是 03 章立的那条:用户超限 429,你自己的上游额度不够 503 —— 原样透传上游的 429,用户会以为是自己发太快了。这里要向用户说明限制的恢复条件,不能把所有配额问题都表现成「再等一下」。

本项目把暂时速率限制与需人工处理的配额耗尽分开编码。能计算恢复时间时提供 Retry-After,但它是否存在不是选择 429 的协议判据。 本月额度耗尽且需充值时,本项目选择 403 + quota_exhausted,提示用户处理;其他 API 可以约定为 429。客户端应读业务 code,不能仅凭有无这个头猜测何时恢复。


🔄 换个栈怎么对应

概念 Python / FastAPI(本板块主栈) Node(Express / Hono) Go
路由带路径参数 @app.get("/conversations/{cid}") app.get('/conversations/:cid') 🗓️ Go 1.22+ 标准库:mux.HandleFunc("GET /conversations/{cid}", h)
指定状态码 status_code=202 res.status(202) / c.json(x, 202) w.WriteHeader(http.StatusAccepted)
设 Location 头 resp.headers["Location"] = ... res.location(url) w.Header().Set("Location", ...)
抛带码的错误 raise HTTPException(409, ...) 抛 HTTPException / next(err) 返回 error,自己映射成码
⚠️ 校验失败默认给哪个码 ⭐ 422(Pydantic 自动) 要自己定(Zod 失败你自己 catch,常写成 400) 没有默认,全靠自己判

⭐ 表里没有「方法语义、状态码语义」这一行,是因为那一件事三家一模一样 —— 它属于 HTTP,不属于框架,换栈根本不会动它。⭐ 所以这张表要看出的是:只有最后一行三家真不同,而它恰恰是换栈时最容易被忽略的一行。 客户端如果按 422 分诊「参数不合法」,代码搬到 Node 就全掉进 400 分支 —— ⚠️ 而两个码都是 4xx、都进死信,粗粒度监控完全看不出来,只有细粒度的错误分类会静默失真。剩下几行的差别全是拼写差别。


🔗 这一章连到哪里

去哪 为什么
03c · 幂等与条件请求 ⭐ 本章只说了「PUT 幂等、POST 不幂等」这个承诺;怎么让不幂等的 POST 也能安全重发整章在那边
03 · 后端骨架 本章第六节直接接它的 code / message / trace_id,以及「用户超限 429、上游额度不够 503」
04 · 调用层 ⭐ 那张重试白名单是客户端视角,本章是服务端视角。两张表必须对得上 —— 你返的码,别人正是按那张表处置的
05 · 流式输出 唯一一处状态码用不了的地方 —— 所以本章这些码必须在第一个字之前全部用完
06 · 关系数据库 本章 URL 层级里的 conversations / messages 就是那两张表;⭐「用户消息先单独提交」在本章变成 202 响应里的 user_message_seq
08 · 认证会话与多租户 401 / 403 / 404 的选择在那一章变成越权防御:本章给「返哪个码」的判据,那一章讲怎么从结构上保证不漏
11 · 长任务与队列 ⭐ 本章补的正是它那条「400/401 死信、429/500 重试」规则的生产端;它第三节那张「轮询 vs SSE」的表,上游就是本章第五节的 202 + job 资源
12 · 限流配额与成本护栏 429 的 Retry-After 怎么算。这是本项目的限流响应约定;协议允许 429 不带该字段,业务配额需结合 code 判断
智能体工程 07 · 工具设计 | 08 · MCP ⚠️ 看起来矛盾,其实不是:那两章说「一个工具应该对应人类的一个任务意图,而不是数据库的一张表或 REST API 的一个端点」,说的是给模型用的工具;本章说的是给客户端用的接口。⭐ 两者是上下游 —— Cloudflare 用两个工具覆盖约 2500 个 API 端点,前提正是那 2500 个端点存在且划得清楚

✅ 检查点

  1. 这一章补的是第 11 章那条重试/死信规则的哪一半?举一个「写错状态码,对面就做错决定」的例子。
  2. URL 里写动词(POST /createConversation)跟「好不好看」无关的那个代价是什么?
  3. 判断「该不该单独建一个资源」的判据是什么?
  4. 为什么说方法是承诺而不是规矩?DELETE 连发两次第二次该返什么、为什么?
  5. 201 和 202 分别承诺了什么?任务查询返回 200 / failed 时,页面下一步做什么?
  6. 401 和 403 分错会造成什么具体症状?跨租户访问该返 404 还是 403,判据和代价各是什么?
  7. 409 是否一定能靠等待恢复?已完成任务取消与短暂锁冲突分别怎么办?
  8. 「用户配额用完了」该返 429 还是 403?本章给的判据是哪一句?
  9. 换到 Node 或 Go,本章哪一行会真的变?为什么这个变化在监控上看不出来?
👀 答案
  1. 补的是生产端 —— 服务端按什么判据把错误分进那几个码(11 章讲的是客户端拿到码之后怎么处置)。例子任选:「prompt 超长」返 500 会被按白名单重试 3 次,本该 0.2 秒的错拖成 8 秒、日志里还像上游在抖;「上游 502」翻成 400 会一次进死信,丢掉本该重试一次就好的活。
  2. 代价是方法全变成 POST,于是代理、CDN、浏览器、日志、限流器、重试器看到的都是一个不透明的 POST —— 能不能缓存、重发安不安全、是读还是写全推不出来。信息藏在 URL 字符串里,没有中间层会去读。
  3. 它有没有自己的生命周期:需不需要被单独查询、单独重试、单独取消。3 分钟的 PDF 总结有 queued / running / done、有查进度和取消的需求,所以必须有自己的 id;300 毫秒返回的没有中间状态,就只是一次 POST。
  4. 因为客户端和中间层真的照着它行事,不问你一句 —— GET 上的删除会被预取、被 CDN 缓存住「成功」、被重试器自动重发,参数还进各层日志。DELETE 本例两次返 204;第二次按契约返 404 也可符合幂等,比较的是预期效果。
  5. 201 确认承诺的资源已创建,202 只确认请求已接受处理。本例通过任务地址查询。200 / failed 表示任务记录读取成功、摘要生成失败。页面显示失败原因,停止轮询,并保留已提交的用户消息。
  6. 401 是缺少有效认证凭证,先按认证挑战处理;403 是当前请求被拒,不以同凭证原样自动重试。新凭证或权限/策略改变可能恢复,不能因 403 固定跳登录。混用的症状是登录成功 → 又被跳回登录页 → 无限循环,而日志里全是成功的登录。跨租户判据:403 承认了这个 id 存在,id 可枚举时就成了探测接口,所以「存在与否本身敏感就返 404」。代价是自己排查时分不清「真没有」和「没权限」,解法是对外 404、日志里记真实原因和 trace_id。
  7. 409 是资源状态冲突。已完成的任务不能通过等待变回可取消;短暂锁冲突也只有在契约说明可恢复、重发安全且有预算时才退避。不能按状态码统一决定重试或死信。
  8. 区分暂时速率限制和需人工处理的配额耗尽,读业务 code。本项目分别使用 429 和 403;这不是协议唯一选择。429 的 Retry-After 可选,缺省不能理解为立即重试。
  9. 校验失败默认给哪个码:FastAPI / Pydantic 自动给 422,Node 里 Zod 要你自己 catch(常写成 400),Go 标准库没有默认。看不出来是因为 400 和 422 都是 4xx、都进死信,粗粒度监控完全一致,只有细粒度的错误分类会静默失真。其余几行三家一个字都不用改 —— 它们属于 HTTP 不属于框架。

本节回顾

⚡ 走神救援

⭐ 主判据:每个状态码都在回答「这是谁的错、对面该不该再发一次」。

两个方向都疼:把「prompt 超长」返 500,会被重试三次、把 0.2 秒的错拖成 8 秒还伪装成上游在抖;把上游 502 翻成 400,会一次进死信,丢掉本该重试一次就好的活。

⭐ 方法是承诺不是规矩:GET 安全且幂等,所以会被预取、被缓存、被自动重发。💀 把删除写成 GET,会被预取器扫光、被 CDN 缓存住「成功」、被重试器重发。生成天然不幂等,所以发消息就该是 POST。

状态码说明结果;可恢复性、重发安全和预算共同决定是否重试。 ⭐ 201 = 已经成了喏在这儿,202 = 排上了成不成还不知道;⭐ 401 先处理认证凭证,403 先核对拒绝原因,不以同凭证原样自动重试(混用会造成登录无限循环,而日志里全是成功的登录)。409 要先解决状态冲突;已完成任务的取消不应盲目重试。

跨租户返 404 还是 403:403 承认了这个 id 存在,所以存在性本身敏感就返 404,代价是自己排查分不清——解法是对外 404、日志记真实原因和 trace_id。⚠️ 判断顺序也是设计:认人 → 归属 → 权限 → 状态。

⚠️ 流式响应头发出后,后续失败要看正文事件和流是否正常结束。

⭐ 一次对话可以同时产生消息和任务。本例用 202 给出任务入口。查询时按任务状态决定继续等、显示失败,或去结果地址读取那条助手消息。

429 的 Retry-After 是可选字段。暂时速率限制与需充值的配额耗尽,在本项目用不同 code 和处理提示区分,不能拿字段是否存在当协议分界。

下一节 👉 03c-幂等与条件请求.md

打卡记录保存在你的浏览器里,首页能看到总进度