402 是什么
402 Payment Required 在 RFC 9110 §15.5.3 中仍是「保留未定义」的状态码：最初为数字支付场景预留，长期没有标准化语义。它的实际使用集中在商业 API：余额耗尽、套餐到期、未开通付费能力时返回 402，并在响应体里说明充值或升级路径。
基本信息
| 名称 | 402 Payment Required |
|---|---|
| 类别 | 4xx 客户端侧拒绝 |
| 规范 | RFC 9110 §15.5.3（保留未定义） |
| 常见实现 | 付费 API 的余额不足与配额拒绝 |
| 配套要求 | 响应体应说明充值或升级方式 |
| 注意 | 不是通用标准错误码，语义由服务自行约定 |
典型使用场景
- 付费 API 余额不足：客户端读到 402 时弹充值提示而不是普通错误弹窗
- 云服务配额耗尽：区分「请求语法错误」与「账户余额不够」
- 计费中间件：在业务逻辑之前完成账务校验并拒绝
- 客户端 SDK 设计：为 402 准备专门的用户提示文案
- 客服排查：判断报错该走充值流程还是权限申请流程
- 接口文档约定：明确 402 的响应体结构与充值跳转字段
业务处理与响应结构
业务处理与响应结构
curl -si https://api.paid.example.com/v1/query -H 'Authorization: Bearer <token>'
# HTTP/1.1 402 Payment Required
# Content-Type: application/problem+json
# {"title":"insufficient_balance","balance":0,"topup_url":"https://..."}
# 关键：把充值入口放进响应体，而不是只给一个状态码计费与权限相关状态码
| 状态码 | 含义 | 使用建议 |
|---|---|---|
| 401 | 未认证 | 缺凭证或凭证已失效 |
| 403 | 已认证但无权限 | 权限不足、账号被封禁 |
| 402 | 需要付费或余额不足 | 计费类拒绝，需在接口文档中约定 |
| 429 | 请求过于频繁 | 限流，配合 Retry-After 一起返回 |
402 不是标准通用错误码，各服务语义不同；对接前先看对方文档，客户端不要对它套用统一文案。
别把权限不足写成 402：无权限用 403，付费问题才用 402，否则调用方无法区分「去充值」与「去申请授权」。
若能同时给出机器可读的错误标识（如 insufficient_balance），客户端就能区分不同的付费原因，避免一个弹窗应对所有情况。
网关与 SDK 把 402 与 429 分开处理后，用户可以分别得到「去充值」与「稍后重试」两类明确指引。