如何调试 REST API 错误:CORS、401、403、404、415 与超时

作者:Sayaib Sarkar更新于 阅读约 6 分钟

本页内容 9 个小节

简短回答:在应用之外复现失败的请求,先读状态码和响应体,然后每次只改一处。大多数 API 问题都属于少数几种模式,状态码会告诉你是哪一种。如果浏览器提示“blocked by CORS policy”,但同样的请求在 API 客户端中能正常工作,那么问题出在服务器的 CORS 响应头上,而不是你的请求。

本指南会介绍开发者在对接 API 时最常遇到的错误、每种错误的真正含义,以及如何在 VS Code 中用几分钟确认原因。

第 1 步:在应用之外复现请求

你的应用会增加很多层:HTTP 库、拦截器、代理、浏览器。先把它们去掉。

  1. 在浏览器中打开 DevTools → Network,右键点击失败的请求,选择 Copy → Copy as cURL。
  2. 在 VS Code 中打开 DevSnip Pro 的 REST API 客户端,把 cURL 命令粘贴到地址栏。方法、请求头和请求体都会被导入。
  3. 发送请求。现在你可以每次只修改一个请求头,并立即看到效果。

如果请求在这里能用、在浏览器中失败,请直接跳到 CORS 部分。如果两边都失败,下面的状态码会告诉你该看哪里。

读懂状态码和响应体

在修改代码之前,先看看服务器返回了什么。很多 API 会在响应体中解释问题,例如 {"error": "invalid_token", "error_description": "The access token expired"}。

状态码通常的含义首先检查
400 Bad Request请求体或参数无效响应体;必填字段;JSON 语法
401 Unauthorized没有发送有效的凭据Authorization 请求头;令牌是否过期
403 Forbidden凭据有效,但无权执行此操作令牌的作用域或角色;API 密钥的权限
404 Not FoundURL 错误,或资源不存在基础 URL、路径、末尾斜杠、API 版本
405 Method Not AllowedURL 正确,方法错误GET 还是 POST;Allow 响应头
415 Unsupported Media Type服务器无法读取请求体格式Content-Type 请求头
422 Unprocessable EntityJSON 有效,但未通过校验响应体中的字段错误列表
429 Too Many Requests触发了速率限制Retry-After 响应头
5xx服务器出错服务器日志;换一个输入是否正常

401 Unauthorized:凭据没有送达或无效

  • 请求头真的存在吗?有些 HTTP 客户端在跟随重定向到其他主机时会丢掉 Authorization。请检查实际发出的请求,而不是构造请求的代码。
  • 格式正确吗?大多数 API 要求 Authorization: Bearer <token>,中间恰好一个空格,Bearer 只出现一次。如果令牌保存时带了前缀,就很容易出现 Bearer Bearer … 这样的重复错误。
  • 令牌过期了吗?把 JWT 粘贴到 DevSnip Pro 的 JWT Decoder & Signer 中:它会显示头部和声明,并检查 exp。同时把 aud(受众)和 iss(签发者)与 API 的要求进行比较。解码器在本地运行,因此真实令牌绝不会被发送到任何网站。

403 Forbidden:身份没问题,但操作不被允许

服务器知道你是谁,但你的令牌或密钥没有执行此操作的权限。请查看令牌声明中的作用域或角色、API 密钥的权限,以及该资源是否属于另一个账号或租户。除非新令牌拥有更多权限,否则用新令牌重试同一个请求也无济于事。

有些服务器在防火墙或 WAF 拦截请求时(例如缺少 User-Agent)也会返回 403。这种情况下,响应体通常看起来像 HTML 错误页面,而不是 JSON。

404 Not Found 与 405 Method Not Allowed

把 URL 与 API 文档逐字符比对:

  • 基础 URL 和 API 版本(/v1/ 还是 /v2/)。
  • 末尾斜杠:在很多服务器上,/users 和 /users/ 是不同的路由。
  • 从未被替换的路径参数,例如 /users/undefined 或 /users/{id}。

用 {{baseUrl}} 这样的环境变量表示主机,而不是在每个请求中写死,可以避免一整类此类错误。如果路径正确却得到 405,说明该路由存在但不支持这个方法;Allow 响应头会列出它支持的方法。

415 和 400:请求体不是服务器想要的

JSON 请求体需要 Content-Type: application/json。缺少它时,很多框架根本不会解析请求体,你的处理函数看到的就是空的。这会表现为 415,或者表现为 400,并抱怨缺少必填字段——尽管你明明发送了。

HTTP
POST /v1/users HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer <token>

{"name": "Ada", "role": "admin"}

如果服务器需要表单数据,请发送 application/x-www-form-urlencoded(OAuth 令牌端点通常如此)。要在发送前对照 API 的 Schema 检查 JSON 请求体,请使用 DevSnip Pro 的 JSON Schema Validator:它会列出每一处违规及其路径。

CORS:“blocked by CORS policy”

CORS 只由浏览器强制执行。curl、Postman、移动应用和服务器之间的调用都会忽略它,这就是为什么同一个请求在 API 客户端中能用,在你的 Web 应用中却失败。修复永远在服务器端:服务器必须为你页面的源发送正确的 Access-Control-* 响应头。

常见原因:

  • 没有 Access-Control-Allow-Origin 响应头,或者其中的源不对。http://localhost:3000 和 http://localhost:5173 是不同的源。
  • 预检 OPTIONS 请求失败。带 JSON 请求体或 Authorization 请求头的请求会触发预检。如果服务器对它返回 401、404 或 405(通常是因为认证中间件在 CORS 之前运行),浏览器就会拦截真正的请求。
  • 携带凭据时使用了通配符。使用 Cookie(credentials: 'include')时,服务器必须返回确切的源以及 Access-Control-Allow-Credentials: true。不允许使用 Access-Control-Allow-Origin: *。
  • 错误响应没有 CORS 响应头。如果服务器返回不带 CORS 响应头的 500,浏览器会报告 CORS 错误,掩盖真正的错误。请在错误响应中也返回 CORS 响应头。

DevSnip Pro 的 CORS Builder & Debugger 为此提供三种模式:粘贴控制台错误,获取可能的原因和修复方法;粘贴响应头,像浏览器一样检查它们;或者为 Express、NestJS、Next.js、Fastify、nginx 或 FastAPI 生成正确的配置。

超时与一直不结束的请求

  • 先确认确实有程序在监听。DevSnip Pro 的 Port & Network Toolkit 会显示哪些本地端口是空闲的:如果你的 API 应该使用的端口是空闲的,说明服务器没有在那里运行。
  • 从手机或模拟器请求 localhost,访问的是设备本身,而不是你的电脑。请使用电脑在局域网中的地址,或模拟器为宿主机提供的别名。
  • 大型响应和较慢的端点可能需要更长的超时时间。在 DevSnip Pro 中,devsnip.apiTimeout 设置默认值(30 秒),单个请求的超时会覆盖它,Cancel 可以提前停止请求。

然后在代码中修复

当请求在 API 客户端中能正常工作后,生成同样调用的 JavaScript(fetch 或 Axios)、Python、Go、Java 或 C# 代码,并与你的代码进行比较。差异通常在于某个请求头、请求体的编码方式或 URL。

在你自己的编辑器中试试

免费、无需账号、本地运行。支持 Windows、macOS 和 Linux 上的 VS Code 1.93+ 与 JetBrains IDE。

code --install-extension sayaib.hue-console