这一章把重点从“页面能不能看”推进到“接口为什么出错”。
对小白来说，后端报错最常见的感受就是：看不懂状态码，看不懂返回值，也不知道该把哪些信息给 AI 编程助手。
学完这一章，你应该能做到：
- 把接口报错说给 AI 编程助手听；
- 让 AI 编程助手按排查顺序分析问题；
- 学会收集状态码、请求地址、返回体、日志这些关键信息；
- 不再只丢一句“接口报错了”。
如果还没有打开可用的 AI 编程工具，先按第一章从官网安装并完成第一个练习，再继续这一章。
本章可直接复制的提示词
你要做的事：接口报错了，不知道该发什么给 AI。
【可直接复制给 AI】
接口报错了，我是编程小白。
这是我看到的信息：
状态码：（填写 401/403/404/429/500 等）
请求地址：（粘贴 URL）
报错内容：（粘贴完整报错）
请不要直接改代码。
请告诉我：
1. 这个状态码通常是什么意思；
2. 最可能的 3 个原因；
3. 我下一步应该复制哪些信息给你；
4. 哪些文件或配置不要随便改。
【说明】
- AI 会解释状态码；
- 告诉你最可能的问题方向；
- 告诉你下一步要补充哪些日志或截图。
不满意继续这样问：
请按最可能到最不可能排序。
只告诉我第一步应该检查什么，不要列太多理论。
8.1 接口报错，不要只把状态码丢给 AI 编程工具
前端页面坏了，至少你还能看见按钮歪了、页面乱了、文字溢出了。
但 API 报错不一样。
它经常只给你一个冷冰冰的状态码：
401 Unauthorized
403 Forbidden
404 Not Found
429 Too Many Requests
500 Internal Server Error
新手看到这些状态码，经常会直接问：
接口 401 了，怎么修？
或者：
接口 500，帮我修。
这类问题太短，AI 编程工具很容易猜。
因为同样是 401，原因可能完全不同：
没有传 API Key
API Key 写错
Bearer 格式错了
Token 过期
服务端没读到环境变量
前端请求没有带 cookie
登录中间件拦截了
请求到了错误的环境
同样是 404，也可能是：
路径写错
路由文件位置错
请求方法错
base URL 错
本地服务没启动
接口部署到了另一个域名
动态路由参数缺失
所以第八章要教的不是“背状态码”，而是让 AI 编程工具按真实后端项目的方式排查。
这一章我们会用几个常见接口写法做案例：
Next.js Route Handler：最常见的前后端一体接口
Hono API：轻量后端和边缘函数项目常见
tRPC：类型安全接口项目常见
Auth.js / NextAuth：登录认证报错常见
AI Chatbot / API Gateway：模型接口、Key、Base URL 报错常见
本章的核心原则：
接口报错时，不要只给 AI 编程工具状态码，要同时给它请求、返回、路由文件、环境变量和服务端日志。
8.2 先做一个“API 报错诊断 Skill”
第六章我们做了“项目启动体检 Skill”。
第七章我们做了“落地页审美 Skill”。
第八章可以做一个新的 Skill：
api-error-doctor
中文叫：
API 报错诊断 Skill
它的作用是：
每次接口报错时，让 AI 编程工具先按固定顺序查证据，而不是直接猜原因。
API 报错诊断 Skill 示例
# API 报错诊断 Skill
当用户遇到接口请求失败、状态码错误、登录失败、模型 API 调用失败、前后端联调失败时，使用本 Skill。
## 目标
先根据请求、响应、日志、路由文件和环境变量定位问题，不要一上来修改代码。
## 必须收集的信息
1. 请求 URL
2. 请求方法：GET / POST / PUT / DELETE
3. 请求 Headers
4. 请求 Body
5. 响应状态码
6. 响应 Body
7. 浏览器 Network 面板错误
8. 服务端终端日志
9. 相关 API 路由文件
10. 环境变量配置方式
## 诊断顺序
1. 判断请求是否打到了正确域名和路径。
2. 判断请求方法是否正确。
3. 判断是否缺少 Header。
4. 判断是否缺少 Body 参数。
5. 判断是否缺少环境变量。
6. 判断是否被登录、权限、中间件拦截。
7. 判断是否是上游第三方 API 返回错误。
8. 判断是否是服务端代码抛异常。
9. 判断是否是前端解析返回值失败。
10. 最后才提出修改代码方案。
## 输出格式
- 状态码：
- 最可能原因：
- 当前证据：
- 还缺哪些信息：
- 应该查看的文件：
- 不应该先改的地方：
- 最小排查步骤：
- 可能的最小修复方案：
## 禁止事项
- 不要只根据状态码下结论。
- 不要编造 API Key。
- 不要暴露用户密钥。
- 不要修改支付、登录、权限代码，除非用户确认。
- 不要把 500 一律归因于服务端代码。
- 不要把 401 一律归因于 Key 错。
- 不要一上来重构接口。
不做 Skill，也可以直接复制这段提示词
请作为 API 报错诊断助手帮我排查接口问题。
要求：
1. 先不要修改任何文件
2. 不要只根据状态码下结论
3. 先收集请求 URL、方法、Headers、Body、响应状态码、响应内容、服务端日志
4. 判断请求是否打到正确路径
5. 判断是否缺少鉴权、参数、环境变量或上游服务配置
6. 给出最小排查步骤
7. 最后再判断是否需要改代码
输出格式：
- 状态码：
- 最可能原因：
- 当前证据：
- 还缺哪些信息：
- 应该查看的文件：
- 不应该先改的地方：
- 最小排查步骤：
- 可能的最小修复方案：
8.3 案例一：AI Chatbot 接口 500，不一定是代码炸了
第一个真实场景：
你 clone 了一个 AI Chatbot 模板。
页面能打开，输入消息后，聊天接口报错。
浏览器 Network 里看到：
POST /api/chat
500 Internal Server Error
终端里可能看到：
OPENAI_API_KEY is not set
Invalid API key
model not found
fetch failed
Cannot read properties of undefined
很多人第一反应是：
接口 500 了，帮我修代码。
但 AI Chatbot 的 500，不一定是代码 bug。
它可能是：
模型 API Key 没配
Base URL 不对
模型名不对
上游接口返回错误
请求 body 格式不对
流式响应处理失败
服务端环境变量没读到
本地 .env 没生效
推荐提示词
AI Chatbot 项目里，聊天接口 POST /api/chat 返回 500。
请先分析原因，不要修改任何文件。
下面是信息：
请求 URL：
{填入请求地址}
请求方法：
POST
请求 Body：
{填入请求体}
响应状态码：
500
响应内容：
{填入响应内容}
服务端日志：
{粘贴终端日志}
请你帮我判断：
1. 这是代码错误、环境变量错误，还是上游模型 API 错误
2. 是否缺少 API Key、Base URL 或模型名
3. 应该查看哪些文件
4. 是否需要检查 .env / .env.local
5. 最小排查步骤是什么
6. 暂时不要修改代码
AI 编程工具应该重点看哪些文件
AI Chatbot 类项目常见文件包括：
app/api/chat/route.ts
src/app/api/chat/route.ts
lib/ai/*
lib/openai/*
lib/models.ts
.env.example
.env.local
package.json
如果项目用了 AI SDK，可能还会有：
ai/providers.ts
lib/ai/models.ts
lib/ai/prompts.ts
最常见的错误：环境变量没生效
很多新手以为自己配好了：
OPENAI_API_KEY=
但这里是空的。
或者写成：
OPENAI_KEY=
而代码里读的是：
process.env.OPENAI_API_KEY
变量名不一致，服务端就读不到。
可以让 AI 编程工具这样查：
请搜索项目中所有 process.env 的使用位置。
重点检查：
1. 聊天接口需要哪些环境变量
2. .env.example 里是否列出了这些变量
3. .env.local 是否需要手动创建
4. 变量名是否一致
5. 哪些变量不能用空值
不要把密钥贴给 AI 编程工具
你可以贴变量名，但不要贴真实 Key。
正确写法：
我已经配置了 OPENAI_API_KEY，但不粘贴真实值。
请帮我判断代码读取的变量名是否正确。
不要这样：
这是我的 API Key：sk-xxxx，帮我看看对不对。
如果是模型名错误
比如响应里出现：
model not found
unsupported model
invalid model
不要让 AI 编程工具直接乱换模型。
提示词：
接口返回 model not found。
请先分析原因，不要修改代码。
请帮我检查：
1. 当前代码里模型名在哪里配置
2. 模型名是否来自环境变量
3. 是否可能是 provider 和 model 不匹配
4. 是否需要区分 OpenAI-compatible endpoint 和官方 endpoint
5. 请给出检查步骤，不要直接替换模型名
最小修复思路
如果只是环境变量缺失，可能不需要改代码。
你只需要：
创建 .env.local
填写正确变量
重启 dev server
重新请求接口
如果是接口代码没有处理错误，可以再让 AI 编程工具加一个更友好的错误返回。
但要先确认：
根因是配置问题，不是代码结构问题。
8.4 案例二：Next.js Route Handler 404，可能是路径或方法错了
第二个常见场景：
你写了一个接口，前端请求一直 404。
比如你请求：
/api/create
但接口文件可能是：
app/api/create/route.ts
或者：
pages/api/create.ts
不同接口写法，规则不一样。
新手最容易混淆：
App Router
Pages Router
Route Handler
API Route
动态路由
请求方法
所以 404 不一定是接口不存在，也可能是你请求方法错了。
推荐提示词
前端请求接口返回 404。
请先分析当前项目，不要修改文件。
请求信息：
URL：
{填入 URL}
方法：
{GET 或 POST}
响应内容：
{填入响应内容}
请帮我检查：
1. 项目使用 App Router 还是 Pages Router
2. 对应 API 路由文件应该放在哪里
3. 当前项目里是否存在对应 route.ts 或 api 文件
4. 请求方法是否和代码里的 GET / POST 导出一致
5. 是否存在动态路由参数缺失
6. 最小修复方案是什么
先只分析，不要修改。
AI 编程工具应该检查的文件
Next.js App Router 常见：
app/api/xxx/route.ts
src/app/api/xxx/route.ts
Pages Router 常见：
pages/api/xxx.ts
src/pages/api/xxx.ts
如果是动态路由：
app/api/users/[id]/route.ts
pages/api/users/[id].ts
请求方法也会导致问题
比如接口只写了：
export async function POST() {
// ...
}
但前端用的是：
fetch('/api/create')
默认是 GET。
这就可能不对。
你可以让 AI 编程工具检查：
请对比前端 fetch 的请求方法和 route.ts 中导出的 GET / POST 方法是否一致。
最小修复提示词
请给出最小修复方案。
限制：
1. 不要重构接口目录
2. 不要同时兼容所有请求方法
3. 不要修改无关页面
4. 只修复当前请求和当前路由不匹配的问题
5. 修改前先说明要改哪个文件
翻车点
不要让 AI 编程工具看到 404 就新建接口。
错误提示词：
404 了，帮我新建一个接口。
更好的提示词：
先检查现有项目里是否已经有对应接口，不要重复创建。
8.5 案例三：Hono API 返回 400，先查验证器和请求 Body
第三个案例用 Hono 这类轻量 API 项目。
Hono 项目常见在：
Cloudflare Workers
Bun
Deno
Vercel Edge
轻量 API 服务
边缘函数
内部工具 API
这类项目很多会搭配：
Zod
Valibot
validator middleware
自定义 middleware
如果请求返回 400，不一定是接口坏了。
很可能是验证器拒绝了请求。
常见场景
你请求：
POST /api/users
Body 里传：
{
"email": "test@example.com"
}
但后端要求：
{
"email": "test@example.com",
"name": "Tom"
}
少了 name，验证器返回 400。
推荐提示词
Hono API 返回 400。
请先分析当前项目，不要修改文件。
请求信息：
URL：
{填入 URL}
方法：
{填入方法}
请求 Body：
{填入 Body}
响应内容：
{填入响应}
请帮我判断：
1. 这是路由不存在，还是请求参数校验失败
2. 是否有 Zod / Valibot / validator middleware
3. 这个接口要求哪些字段
4. 当前请求缺少哪些字段
5. 是否是 Content-Type 不对
6. 最小修复方案是什么
先只分析，不要修改。
AI 编程工具应该看哪些文件
Hono 项目常见：
src/index.ts
src/routes/*
src/middleware/*
src/validators/*
src/schema/*
worker.ts
如果是 Cloudflare Workers：
wrangler.toml
src/index.ts
如果项目有 OpenAPI 生成：
openapi.ts
schema.ts
routes/*
Content-Type 也很常见
很多 API 要求：
Content-Type: application/json
但前端 fetch 忘了写。
错误写法：
fetch('/api/users', {
method: 'POST',
body: JSON.stringify(data)
})
更完整的写法：
fetch('/api/users', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify(data)
})
你可以让 AI 编程工具对比前后端：
请对比前端 fetch 请求和 Hono 后端验证逻辑。
重点检查：
1. Content-Type
2. Body 字段
3. 字段类型
4. 必填字段
5. 返回错误格式
不要让 AI 编程工具放宽校验
新手看到 400，很容易让 AI 编程工具：
把校验去掉。
这很危险。
更好的说法：
请不要删除校验。请判断是前端请求应该补字段，还是后端错误提示应该更友好。
最小修复思路
400 的修复通常有两种：
第一种，前端传错了。
修前端请求 Body
补 Content-Type
补必填字段
修字段类型
第二种，后端错误提示不友好。
保留校验
返回更清楚的错误 message
告诉前端缺哪个字段
不要直接删验证器。
8.6 案例四：Auth.js 登录 401 / 403，先查 Secret、Cookie 和回调地址
登录接口是最容易把人搞崩的。
你点登录按钮，可能遇到：
401 Unauthorized
403 Forbidden
Callback URL mismatch
MissingSecret
Invalid provider
OAuthAccountNotLinked
CSRF token mismatch
这类问题不能只看前端。
它可能涉及：
环境变量
OAuth Provider 配置
回调地址
Cookie
中间件
Session
部署域名
本地 localhost
推荐提示词
Auth.js / NextAuth 登录失败，返回 401 或 403。
请先分析当前项目，不要修改文件。
我提供的信息：
登录方式：
{Google / GitHub / 邮箱 / Credentials}
错误状态码：
{401 / 403}
错误内容：
{粘贴错误}
当前环境：
{本地 / 预览环境 / 生产环境}
请帮我判断：
1. 是否缺少 AUTH_SECRET 或 NEXTAUTH_SECRET
2. 是否是回调地址配置错误
3. 是否是 Cookie / Session 问题
4. 是否是中间件拦截
5. 是否是 OAuth Provider 配置问题
6. 需要查看哪些文件
先只分析，不要修改。
AI 编程工具应该看哪些文件
常见文件包括：
auth.ts
middleware.ts
app/api/auth/[...nextauth]/route.ts
pages/api/auth/[...nextauth].ts
.env.example
.env.local
next.config.js
如果是 Credentials 登录，还可能看：
lib/auth.ts
lib/db/*
schema/*
users table
最常见：Secret 没配
有些登录库在生产环境必须配置 secret。
不要把真实 secret 粘贴给 AI 编程工具。
可以这样问：
我不粘贴真实 secret。
请帮我检查：
1. 项目代码读取的是 AUTH_SECRET 还是 NEXTAUTH_SECRET
2. .env.example 是否写了这个变量
3. 本地和生产环境是否都需要配置
4. 缺少 secret 会出现什么错误
回调地址错误
OAuth 登录经常卡在 callback。
比如本地是：
http://localhost:3000/api/auth/callback/github
生产是：
https://example.com/api/auth/callback/github
如果 Provider 后台填错，就会失败。
你可以让 AI 编程工具输出检查清单：
请给我一份 OAuth callback 排查清单。
要求包括：
1. 本地回调地址
2. 生产回调地址
3. 环境变量里的 APP_URL / NEXTAUTH_URL
4. Provider 后台配置
5. middleware 是否拦截 callback 路径
6. cookie secure 设置是否和环境匹配
不要让 AI 编程工具乱改登录逻辑
错误提示词：
登录 403，帮我改 auth。
更好的提示词：
请先判断是配置问题、回调地址问题、cookie 问题，还是代码逻辑问题。不要先改登录逻辑。
8.7 案例五：tRPC 类型没报错，但接口返回不对
tRPC 这类项目的特点是：
前后端类型连得很紧。
这对开发很舒服，但出问题时，新手容易不知道从哪里看。
常见场景：
前端调用 mutation 失败
query 返回 undefined
服务端 procedure 抛错
input schema 不匹配
前端类型对了，但运行时数据不对
推荐提示词
tRPC 接口调用失败。
请先分析当前项目，不要修改文件。
我提供的信息：
调用的 procedure：
{例如 post.create}
前端调用代码：
{粘贴调用片段}
服务端 router：
{粘贴或指定文件}
错误内容：
{粘贴错误}
请帮我判断：
1. 是 input schema 不匹配
2. 是 resolver 逻辑错误
3. 是数据库返回为空
4. 是权限中间件拦截
5. 是客户端调用方式不对
6. 需要查看哪些文件
先只分析，不要修改。
AI 编程工具应该看哪些文件
tRPC 项目常见：
server/api/root.ts
server/api/routers/*
trpc/server.ts
trpc/client.ts
src/server/api/*
src/utils/api.ts
schema/*
如果是 T3 Stack，可能会看：
src/server/api/root.ts
src/server/api/routers/*
src/trpc/*
src/env.js
input schema 很关键
很多 tRPC 接口会用 Zod 校验 input。
比如服务端要求：
input: z.object({
title: z.string().min(1),
content: z.string()
})
但前端传：
{
title: ''
}
这就会失败。
你可以让 AI 编程工具专门对比：
请对比前端传入的 input 和服务端 procedure 的 input schema。
请指出：
1. 缺少字段
2. 字段类型不匹配
3. 字段值不满足 min / max / enum
4. 是否需要前端表单先校验
5. 是否需要后端返回更友好的错误
不要把类型安全当万能
tRPC 可以减少很多前后端字段不一致的问题。
但它不能自动保证：
数据库里一定有数据
用户一定有权限
环境变量一定存在
第三方服务一定可用
业务逻辑一定正确
所以接口报错时，仍然要看运行时日志。
提示词：
虽然这是 tRPC 项目，但请不要只看 TypeScript 类型。
请同时检查：
1. 运行时日志
2. 数据库返回
3. 权限中间件
4. input schema
5. 客户端调用参数
8.8 案例六：429 不是代码坏了，可能是限流或额度问题
429 很常见，尤其是 AI API 项目、支付接口、短信接口、邮件接口、搜索接口。
状态码：
429 Too Many Requests
通常表示：
请求太频繁
额度用完
限流触发
同一个 IP 请求太多
同一个 API Key 请求太多
短时间重试太猛
新手看到 429，经常会让 AI 编程工具：
帮我修接口。
但 429 很多时候不是代码 bug，而是使用方式问题。
推荐提示词
接口返回 429 Too Many Requests。
请先分析当前项目，不要修改文件。
请求信息：
URL：
{填入}
方法：
{填入}
响应内容：
{填入}
请求频率：
{大概多久请求一次}
请帮我判断：
1. 这是本地代码限流，还是上游服务限流
2. 是否和 API Key、IP、用户账号、额度有关
3. 是否有重试逻辑过于频繁
4. 是否需要加 debounce、缓存或队列
5. 是否应该减少自动重试
6. 最小修改方案是什么
AI API 项目里的 429
如果是模型 API，429 可能来自上游。
比如：
余额不足
额度耗尽
RPM / TPM 限制
并发太高
模型服务繁忙
你要让 AI 编程工具分清楚：
429 是我们自己的服务返回的，还是上游模型服务返回的？
提示词：
请根据响应内容和服务端日志判断 429 来自本地接口还是上游 API。
如果来自上游，请不要修改本地限流逻辑。
先给出降低请求频率、增加错误提示、减少自动重试的方案。
不要暴力重试
很多项目遇到请求失败，会自动重试。
如果重试没有限制，就会越重试越 429。
你可以让 AI 编程工具检查：
请检查项目里是否有自动重试逻辑。
重点查看：
1. fetch wrapper
2. API client
3. retry 配置
4. React Query / SWR 配置
5. 队列或轮询代码
不要修改，先输出风险。
合理修复方向
429 的修复通常不是“突破限制”，而是：
减少重复请求
加 debounce
加缓存
给用户友好提示
延长重试间隔
停止无限重试
记录上游错误
不要写成：
绕过限流
突破限制
刷接口
这是错误方向。
8.9 案例七：接口 200 了，但前端还是报错
有时候最迷惑的情况是：
接口返回 200，但页面还是报错。
这说明问题可能不在 HTTP 状态码，而在数据格式。
比如前端期待：
{
"data": {
"items": []
}
}
但后端返回：
{
"items": []
}
状态码是 200，但前端读取：
res.data.items
就会炸。
推荐提示词
接口返回 200，但前端页面仍然报错。
请先分析当前项目，不要修改文件。
我提供信息：
接口返回 JSON：
{粘贴返回}
前端报错：
{粘贴报错}
前端使用数据的代码：
{粘贴代码或指定文件}
请帮我判断：
1. 前端期待的数据结构是什么
2. 后端实际返回的数据结构是什么
3. 哪个字段不一致
4. 应该改前端解析，还是改后端返回
5. 哪种改法影响最小
AI 编程工具应该对比什么
它应该对比：
接口 response
前端类型定义
前端解构代码
组件 props
后端返回对象
错误堆栈
如果项目有类型文件：
types/api.ts
schema.ts
validators.ts
也要一起看。
最小修复思路
两种方向：
第一种，后端返回应该保持现有约定。
改前端解析
第二种，前端多个地方都依赖旧结构。
改后端返回格式
不要让 AI 编程工具随便选。
提示词：
请判断当前项目里这个接口返回结构是否已经被多个地方使用。
如果只影响一个页面，优先改前端解析。
如果多个页面依赖统一 API 格式，优先保持 API 格式一致。
8.10 本章通用模板
下面这些模板可以直接复制。
模板一：API 报错诊断
请作为 API 报错诊断助手帮我排查接口问题。
要求：
1. 先不要修改任何文件
2. 不要只根据状态码下结论
3. 先分析请求 URL、方法、Headers、Body、响应状态码、响应内容、服务端日志
4. 判断请求是否打到正确路径
5. 判断是否缺少鉴权、参数、环境变量或上游服务配置
6. 给出最小排查步骤
7. 最后再判断是否需要改代码
输出格式：
- 状态码：
- 最可能原因：
- 当前证据：
- 还缺哪些信息：
- 应该查看的文件：
- 不应该先改的地方：
- 最小排查步骤：
- 可能的最小修复方案：
模板二：AI Chatbot 接口 500
AI Chatbot 的 POST /api/chat 返回 500。
请先分析当前项目，不要修改任何文件。
信息如下：
请求 URL：
请求 Body：
响应内容：
服务端日志：
请判断：
1. 是代码错误、环境变量错误，还是上游模型 API 错误
2. 是否缺少 API Key、Base URL 或模型名
3. 应该查看哪些文件
4. 是否需要检查 .env / .env.local
5. 最小排查步骤是什么
模板三：接口 404
前端请求接口返回 404。
请先分析当前项目，不要修改文件。
请求 URL：
请求方法：
响应内容：
请检查：
1. 项目使用 App Router 还是 Pages Router
2. 对应 API 路由文件应该在哪里
3. 当前项目是否已有对应接口
4. 请求方法是否和后端导出方法一致
5. 是否是路径、方法或动态参数问题
模板四：Hono / Zod 400
Hono API 返回 400。
请先分析当前项目，不要修改文件。
请求 URL：
请求方法：
请求 Body：
响应内容：
请判断：
1. 是否是请求参数校验失败
2. 是否有 Zod / Valibot / validator middleware
3. 当前请求缺少哪些字段
4. Content-Type 是否正确
5. 应该修前端请求，还是优化后端错误提示
模板五：Auth.js 登录失败
Auth.js / NextAuth 登录失败。
请先分析当前项目，不要修改文件。
登录方式：
错误状态码：
错误内容：
当前环境：
请判断：
1. 是否缺少 AUTH_SECRET / NEXTAUTH_SECRET
2. 是否是 callback URL 错误
3. 是否是 Cookie / Session 问题
4. 是否被 middleware 拦截
5. 是否是 OAuth Provider 配置问题
6. 需要查看哪些文件
模板六：tRPC 接口失败
tRPC 接口调用失败。
请先分析当前项目，不要修改文件。
procedure：
前端调用代码：
服务端 router：
错误内容：
请判断：
1. input schema 是否匹配
2. resolver 是否抛错
3. 是否数据库返回为空
4. 是否权限中间件拦截
5. 是否客户端调用方式不对
6. 最小修复方案是什么
模板七：429 限流
接口返回 429 Too Many Requests。
请先分析当前项目，不要修改文件。
请求 URL：
响应内容：
请求频率：
服务端日志：
请判断：
1. 429 来自本地接口还是上游服务
2. 是否和 API Key、IP、额度、并发有关
3. 是否有自动重试过多
4. 是否应该加 debounce、缓存或队列
5. 如何给用户更友好的错误提示
模板八：接口 200 但页面报错
接口返回 200，但前端仍然报错。
请先分析当前项目，不要修改文件。
接口返回 JSON：
前端报错：
前端使用数据的代码：
请判断：
1. 前端期待的数据结构
2. 后端实际返回的数据结构
3. 哪个字段不一致
4. 应该改前端解析还是后端返回
5. 哪种改法影响最小
8.11 本章总结
接口报错最怕两件事。
第一，信息太少。
只告诉 AI 编程工具：接口 500 了。
第二，改得太快。
还没看请求和日志，就让 AI 编程工具改代码。
正确方式是：
先收集证据，再判断层级，最后做最小修复。
这一章你要记住：
401 不一定是 Key 错。
403 不一定是权限代码错。
404 不一定是接口不存在。
400 不一定是后端坏了。
429 不一定是代码 bug。
500 不一定要重构。
200 也不代表前端一定能用。
接口问题要分层看：
请求层：URL、方法、Header、Body
路由层：接口文件、动态参数、请求方法
鉴权层：Token、Cookie、Session、Secret
校验层：Zod、Valibot、schema、必填字段
环境层：API Key、Base URL、数据库、第三方服务
业务层：数据库返回、权限判断、状态流转
上游层：模型 API、支付、短信、邮件、搜索服务
前端层：返回结构、类型定义、组件解析
推荐工作流：
打开 Network 面板
复制请求和返回
复制服务端日志
让 AI 编程工具判断问题层级
指定相关 API 文件
先输出诊断
确认后最小修改
检查 diff
重新请求接口
确认错误提示是否友好
这章最重要的一句话：
接口报错，不要让 AI 编程工具猜；把请求、返回和日志给它，让它按后端流程查。
下一章可以继续讲：
代码改完以后，怎么让 AI 编程工具审查 diff、找隐藏 bug、检查无关修改，并结合真实 PR 审查场景，让它从“写代码助手”变成“代码审查助手”。