附录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" |
应用日志 + 慢查询 |