Appearance
状态码与媒体类型速查
一页速查表：状态码（RFC 9110 §15 + 关联 RFC）与 API 常用媒体类型（IANA 注册表）。详细说明见HTTP 状态码详解与表示与媒体类型。
1. 状态码总表
1xx 信息
| 码 | 名称 | 一句话 |
|---|---|---|
| 100 | Continue | Expect 试探通过，继续发 body |
| 101 | Switching Protocols | 协议升级（WebSocket） |
| 103 | Early Hints | 提前推送资源提示 |
2xx 成功
| 码 | 名称 | 典型场景 | 义务/建议 |
|---|---|---|---|
| 200 | OK | GET/PUT/PATCH/POST 成功带表示 | — |
| 201 | Created | POST 创建 / PUT upsert 创建 | SHOULD Location |
| 202 | Accepted | 异步受理 | 给作业资源链接 + Retry-After |
| 204 | No Content | DELETE/PUT 成功无返回 | 必须无 body |
| 206 | Partial Content | Range 请求 | Content-Range |
3xx 重定向
| 码 | 名称 | 方法变化 | 场景 |
|---|---|---|---|
| 301 | Moved Permanently | 可能→GET | 永久迁移（老客户端兼容） |
| 302 | Found | 可能→GET | 临时跳转 |
| 303 | See Other | 强制→GET | PRG 模式 |
| 304 | Not Modified | — | 条件 GET 命中，无 body |
| 307 | Temporary Redirect | 不变 | 临时 + 保方法 |
| 308 | Permanent Redirect | 不变 | API 路由迁移首选 |
4xx 客户端错误
| 码 | 名称 | 场景 | 搭档头部/规范 |
|---|---|---|---|
| 400 | Bad Request | 语法/参数错误 | — |
| 401 | Unauthorized | 未认证 | MUST WWW-Authenticate（7235/6750） |
| 403 | Forbidden | 无权限 | problem+json 说明缺什么 |
| 404 | Not Found | 资源不存在 | — |
| 405 | Method Not Allowed | 方法不支持 | MUST Allow |
| 406 | Not Acceptable | Accept 无法满足 | — |
| 408 | Request Timeout | 客户端超时未发完 | 建议 Retry-After |
| 409 | Conflict | 状态/唯一/版本冲突 | — |
| 410 | Gone | 永久消失 | 代替含糊的 404 |
| 411 | Length Required | 缺 Content-Length | — |
| 412 | Precondition Failed | If-Match 不满足（乐观锁） | — |
| 413 | Content Too Large | body 超限 | 可 Retry-After |
| 414 | URI Too Long | 请求行超限 | 改 POST 提交 |
| 415 | Unsupported Media Type | Content-Type 错 | — |
| 416 | Range Not Satisfiable | Range 越界 | Content-Range: */size |
| 417 | Expectation Failed | Expect 无法满足 | — |
| 418 | I'm a teapot | 彩蛋（RFC 2324） | — |
| 421 | Misdirected Request | 连接打错服务 | — |
| 422 | Unprocessable Content | 语义校验失败（4918→9110） | errors[] 批量字段错误 |
| 425 | Too Early | 疑似 0-RTT 重放 | — |
| 428 | Precondition Required | 要求条件头而未带（6585） | 强制乐观锁接口 |
| 429 | Too Many Requests | 限流（6585） | MUST Retry-After |
| 431 | Request Header Fields Too Large | 头部过大（6585） | — |
| 451 | Unavailable For Legal Reasons | 法律屏蔽（7725） | Link: rel="blocked-by" |
5xx 服务器错误
| 码 | 名称 | 场景 |
|---|---|---|
| 500 | Internal Server Error | 未分类异常（带 traceId，无堆栈） |
| 501 | Not Implemented | 方法整个未实现 |
| 502 | Bad Gateway | 上游响应无效 |
| 503 | Service Unavailable | 过载/维护；SHOULD Retry-After |
| 504 | Gateway Timeout | 上游超时 |
| 505 | HTTP Version Not Supported | 协议版本不支持 |
2. 高频辨析卡
400 vs 422 语法错/解析错 → 400；结构对值非法 → 422
401 vs 403 "你是谁" → 401；"你不行" → 403
404 vs 405 URI 不存在 → 404；URI 存在方法错 → 405（带 Allow）
404 vs 410 从未存在/未知 → 404；曾存在已永久删 → 410
409 vs 412 业务规则冲突 → 409；条件头失败 → 412
412 vs 428 带了但过期 → 412；压根没带（强制时）→ 428
429 vs 503 你超速 → 429；我过载 → 503
301 vs 308 都要保方法时 → 3083. 媒体类型速查
| 类型 | 用途 | RFC |
|---|---|---|
application/json | 默认表示 | 8259 |
application/problem+json | 错误表示 | 9457 |
application/merge-patch+json | PATCH 合并补丁 | 7386 |
application/json-patch+json | PATCH 指令补丁（test 操作可内置乐观锁） | 6902 |
multipart/form-data | 文件上传 | 7578 |
application/x-www-form-urlencoded | 表单 | 9110 |
text/event-stream | SSE 推送 | HTML 标准 |
application/hal+json / application/vnd.api+json | 超媒体 / JSON:API | 社区 |
application/octet-stream | 二进制兜底 | 9110 |
application/vnd.{org}.{res}+json | 私有供应商类型 | 6838/6839 |
4. 义务性头部对照
| 状态码 | 头部 | 级别 |
|---|---|---|
| 401 | WWW-Authenticate | MUST |
| 405 | Allow | MUST |
| 429 | Retry-After | MUST（RFC 6585） |
| 503 | Retry-After | SHOULD |
| 201 | Location | SHOULD |
| 416 | Content-Range | MUST（*/总大小） |
| 3xx | Location | SHOULD |