跳到正文
零到全栈 · 卷 9 · 卷 9

附录B HTTP状态码与错误对照

本合集目录
本章目录

一句话定位:状态码不是"成功/失败"两个字,它是一张责任认定书——先看清是谁发的,再决定去翻谁的日志。

什么时候查这个附录

你现在的处境 翻到哪 典型的一句话
浏览器或 curl 回了一个三位数 B-1 "422 到底是我传错了还是后端写错了?"
DevTools 里只有一句 net::ERR_*,没有状态码 B-2 "连接被拒绝,是服务没起还是端口没开?"
页面打不开,但不知道从哪一层开始查 B-2 "先 ping 还是先看 Nginx?"
线上 500/502/504,三选一分不清 B-3 "都是服务器错误,凭什么查的地方不一样?"
改完了,想确认真的修好 B-3 第三步 "三层都通了吗?"
项 说明
适用栈 Nginx(网关)+ FastAPI(应用)+ Next.js(前端)+ SQLite
两条铁律 502/504/413 是 Nginx 发的,500 是应用发的;状态码只看数字,不要匹配原因短语
记号 "谁的问题"列写的是责任层,不是"谁的错"——客户端也可能是被前端代码坑了

B-1 状态码全表

1xx:还在协商,不是最终结果

码 含义 谁的问题 常见触发 怎么办
100 Continue 协议层 客户端带 Expect: 100-continue 发大请求体 不用处理,curl -v 里能看到这一行
101 Switching Protocols 协议层 WebSocket 升级、协议切换 反代要显式转发 Upgrade 与 Connection
103 Early Hints 服务端 先推 Link: rel=preload 让浏览器预加载 多数场景可忽略,别当成最终响应

2xx:成功,但"成功"的形态不同

码 含义 谁的问题 常见触发 怎么办
200 OK 双方 正常返回 别只看码,要看响应体和 Content-Type
201 Created 应用 POST 新建资源成功,通常带 Location 前端从 Location 取新资源地址
202 Accepted 应用 异步任务已接收、尚未完成 必须另有查询接口,别当前端已成功
204 No Content 应用 DELETE/PATCH 成功且无内容返回 不能带响应体;硬塞 JSON 会被截断或报错
206 Partial Content 应用/静态服务 Range 请求、视频拖动、断点续传 看 Content-Range 是否对得上

3xx:跳转,注意"方法会不会被改"

码 含义 谁的问题 常见触发 怎么办
301 Moved Permanently 网关/应用 强制 HTTPS、域名永久迁移 浏览器会长期缓存,配错了很难回退
302 Found 应用 登录后跳转、临时活动页 客户端可能把 POST 改成 GET
303 See Other 应用 POST 之后跳去 GET 结果页 明确告诉客户端"用 GET 去拿"
304 Not Modified 缓存 带 If-None-Match/If-Modified-Since 且内容没变 正常,响应没有体,前端别当失败
307 Temporary Redirect 应用 临时跳转且要保留原方法 与 302 的差别就在"方法不变"
308 Permanent Redirect 网关/应用 永久跳转且保留原方法 和 301 一样会被长期缓存

4xx:请求这一侧有问题(但不一定是用户的错)

码 含义 谁的问题 常见触发 怎么办
400 Bad Request 客户端 JSON 语法错、缺 Host、请求行格式不对 看请求体原文;Nginx 的 400 查 error log
401 Unauthorized 客户端 没带令牌、令牌过期、Bearer 前缀写错 看 WWW-Authenticate;它表示"未认证",不是"没权限"
403 Forbidden 客户端/网关 文件权限不足、目录缺 x、IP 被拒 namei -l + sudo -u www-data cat 复现
404 Not Found 客户端 路径拼错、路由不存在、静态文件没构建出来 先分清是 Nginx 发的还是应用发的
405 Method Not Allowed 客户端 用 GET 打了一个只收 POST 的接口 看响应头 Allow,改方法而不是改路径
406 Not Acceptable 客户端 Accept 里没有服务器能给的类型 少见;检查前端有没有乱设 Accept
408 Request Timeout 客户端/网络 客户端发得太慢,连接空闲超时 调 client_body_timeout,先确认不是弱网
409 Conflict 应用 唯一约束冲突、并发编辑版本号不匹配 前端提示"已被修改,请刷新后重试"
410 Gone 应用 资源已永久删除 比 404 更明确,可顺带给迁移提示
413 Content Too Large 网关 请求体超过 client_max_body_size(默认 1m) 改 Nginx,不是改后端;后端根本没收到
415 Unsupported Media Type 客户端 Content-Type 与接口要求不符 检查 -H 或前端 fetch 的头
422 Unprocessable Content 应用 字段校验失败,FastAPI 默认返回它 看错误体里的 loc 与 msg,别只看码
429 Too Many Requests 应用/网关 触发限流 看 Retry-After,按它退避重试
431 Request Header Fields Too Large 网关 Cookie 太大、请求头太多 清 cookie;调 large_client_header_buffers

5xx:服务端这一侧有问题

码 含义 谁的问题 常见触发 怎么办
500 Internal Server Error 应用 代码抛了未捕获异常 journalctl -u dudao 找 traceback 最后一行
501 Not Implemented 服务端 服务器不支持这个功能或方法 少见;确认不是打到了错误的服务
502 Bad Gateway 网关 上游连不上:没起、端口错、监听地址错 ss -lntp、systemctl status,先证上游活着
503 Service Unavailable 网关/应用 维护、过载、上游整体不可用 看 Retry-After;确认不是重启空窗
504 Gateway Timeout 网关 连上了,但上游在超时内没返回 查慢查询、外部调用、proxy_read_timeout
505 HTTP Version Not Supported 服务端 客户端用了服务器不支持的 HTTP 版本 少见;确认中间层没有篡改协议

另有一个不在标准里、但线上天天见的码:499。它是 Nginx 自己记的"客户端在响应前主动断开",通常意味着接口太慢、用户等不及关了页面。看到 499 不要查客户端,去查那个接口的耗时。

B-2 浏览器报错对照

net::ERR_* 是浏览器在网络层给你的原话;CORS、Mixed Content 是浏览器在策略层拦下来的。两者都没有状态码,所以更容易误判。

你看到的 坏在哪一层 它真正的意思 第一步查什么
net::ERR_CONNECTION_REFUSED TCP 对方端口没人监听,或防火墙直接拒绝 ss -lntp | grep -E '80|443|8000'、systemctl status nginx
net::ERR_CONNECTION_TIMED_OUT 网络/防火墙 包被丢弃,连"拒绝"都没回 云安全组、nc -zv 主机 443、换一个网络试
net::ERR_NAME_NOT_RESOLVED DNS 域名没有记录,或解析失败 dig +short 你的域名,再看 /etc/hosts
net::ERR_CERT_DATE_INVALID TLS 证书过期,或本机时间不对 curl -vI https://域名、服务器 timedatectl、certbot renew --dry-run
net::ERR_CERT_COMMON_NAME_INVALID TLS 证书上的域名和访问的域名不一致 openssl s_client -connect 主机:443 -servername 域名
net::ERR_SSL_PROTOCOL_ERROR TLS 握手失败:https 打到了 http 端口,或协议版本不匹配 curl -vI https://域名,确认 443 的 server 块存在
blocked by CORS policy 浏览器策略 响应被浏览器拦住不给你读,请求往往已经到达服务器 Network 里看状态码,再看 Access-Control-Allow-Origin 与 OPTIONS
Mixed Content(控制台里那条) 浏览器策略 HTTPS 页面里引了 http 的资源 Console 里看被拦的 URL,改相对路径或 // 协议相对
net::ERR_ABORTED 客户端 请求被主动取消:页面跳走、组件卸载、重复请求 看是否路由跳转或 AbortController 触发,多数不是故障
net::ERR_FAILED 混合 一句泛化失败,常是 CORS、证书或被扩展拦 先看 Console 有没有更具体的那一条
net::ERR_EMPTY_RESPONSE TCP/应用 连上了,但一个字节没回就断开 journalctl -u dudao 看是否崩溃,Nginx 看 upstream reset
net::ERR_TOO_MANY_REDIRECTS 应用/网关 跳转成环 curl -IL 看 Location 链;常见于没传 X-Forwarded-Proto
net::ERR_BLOCKED_BY_CLIENT 客户端 被扩展、广告拦截或企业策略拦了 开无痕窗口复测
net::ERR_INTERNET_DISCONNECTED 本机 本机断网 先 ping 网关,别急着查服务器
Failed to load resource: 404 静态资源 页面本身是 200,某个 js/css/图片路径错了 Network 里按 404 过滤,看是绝对路径、basePath 还是大小写
431 Request Header Fields Too Large 网关 请求头(多半是 Cookie)太大 清站点 cookie;检查是否重复下发同名 cookie

表里那个 404 值得单独说:页面能打开、样式全丢、控制台一片红,几乎都是资源 404,而不是页面 404。判断方法只有一个——看 DevTools 里 404 的那条请求 URL,它是 .js、.css、.woff 就属于资源问题;它是文档类型,才是页面路由问题。

B-3 502 / 500 / 504 分诊

这三个码长得像,责任层完全不同。按下面三步走,第三步之前一定能定位到该翻谁的日志。

第一步:确认这页是谁画的

curl -sI https://dudao.example.com/api/notes
curl -s https://dudao.example.com/api/notes | head -c 200
sudo tail -n 5 /var/log/nginx/dudao.access.log
你看到的 说明 去哪
Server: nginx + 一段 Nginx 的 HTML 错误页 网关自己生成的 Nginx error log
Content-Type: application/json + 统一错误结构 请求进了应用 应用日志
浏览器自带错误页,curl 也连不上 连接层就没通 回 B-2

第二步:按码进对应的日志

500——应用抛了异常。

sudo journalctl -u dudao -n 100 --no-pager

找 Traceback 的最后一行,那才是真正的错因;中间的调用栈只是路径。access log 里这条也记 500;若日志格式带了 upstream 字段,有值就说明请求确实转发过去了。

502——根本没连上上游。

systemctl status dudao
sudo ss -lntp | grep 8000
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8000/healthz
sudo grep "connect() failed" /var/log/nginx/dudao.error.log | tail -n 3

顺序不能反:先证明上游活着,再怀疑代理。Connection refused 说明门后没人;如果 ss 看到的是 [::1]:8000 而 proxy_pass 写 127.0.0.1,那就是地址不匹配,服务本身没病。

504——连上了,但没等到回答。

sudo grep "upstream timed out" /var/log/nginx/dudao.error.log | tail -n 3
sudo journalctl -u dudao --since "5 min ago" --no-pager

504 要查"慢在哪":SQLite 写锁排队、一次性统计全表、外部接口没设超时,三选一。把 proxy_read_timeout 调大只是止痛,不是治病。

第三步:修完自证

curl -s -o /dev/null -w 'app %{http_code}\n' http://127.0.0.1:8000/healthz
curl -s -o /dev/null -w 'static %{http_code}\n' -H 'Host: dudao.example.com' http://127.0.0.1/
curl -s -o /dev/null -w 'api %{http_code}\n' -H 'Host: dudao.example.com' http://127.0.0.1/api/notes

三层都 200 才算收口。只有第三层 200、第一层不通,说明你测的是缓存或另一个进程;只有第一层 200,说明问题还在 Nginx 那一跳。

码 一句话指纹 第一个命令 日志在哪
500 应用答的,带 traceback journalctl -u dudao -n 100 应用日志
502 连接没建立 ss -lntp | grep 8000 Nginx error log
504 连接建立了,没等到回答 grep "upstream timed out" 应用日志 + 慢查询