返回知识库

数据与服务 · 网络与接口

服务器错误5xx Error

5xx 表示服务端或上游已返回失败回执,客户端请求通常没错。按码止损:有限退避、尊重 Retry-After;写入先确认幂等,所有 5xx 都应进入监控。

导出受阻:503 后等待,再恢复同一作业

你要导出月度营收。服务端明确返回 503 和 Retry-After: 60;用一次受控重试让相同 job 进入队列,而不是把过载扩大成雪崩。

EXPORT CONTROLrequest-id: req_9af3
月度营收.csvPOST /api/exports
job exp_204
尚未发起导出

这份导出会创建一个异步作业。先发起它,观察服务端返回的可恢复故障。

操作 0/3:导出尚未发送。

5xx 的核心:服务器给了失败回执

5xx 与 network-error 不同:你拿得到 HTTP 状态码,说明请求已到服务端或网关。请求通常没错,故障多半在应用、上游或容量。

500应用未捕获异常保留输入;写入先按幂等键查询或人工确认
502网关拿到上游无效响应读取可退避、有限重试
503过载、维护或熔断,常带 Retry-After等待提示窗口;排队或降级
504网关等待上游超时读取可退避;排查慢依赖

重试规则:指数退避 + 抖动 + 次数上限;503 尊重 Retry-After。GET 等幂等读取可自动重试,创建、支付等写入先确认是否已经执行。

落地:止损、观察、验证,不把异常倒给用户

稳定的 5xx 体验既要给用户恢复路径,也要让工程团队能定位故障。

  • 保留上下文保留表单、job、request-id;未确认完成时不要报成功。
  • 安全地等503 读取 Retry-After;其他可重试请求用带抖动的退避,避免同步重试把恢复中的服务压垮。
  • 写入先查POST 创建、扣款等副作用未知时,用幂等键查询结果或人工确认,避免重复执行。
  • 对内告警将 5xx 按路由、版本与 trace 聚合进监控;对外只给稳定错误码,绝不回显堆栈、SQL 或 token。

同一导出的正反例

503 不是让客户端拼命重发的许可;是否尊重恢复窗口,决定服务会恢复还是被压垮。

正例:503 + Retry-After

页面保留 exp_204,等待窗口后有限重试。服务恢复后同一 job 进入队列,用户知道下一步。

反例:立即并发重试

每次 503 都再开更多请求,worker 更难恢复;写入任务还可能被重复接受,故障被放大。

快速自测

POST 创建订单收到 500,但服务器是否已写入未知,最稳妥的客户端动作是?

继续查证

术语的技术定义和行为以这些一手或权威资料为准。

下一步学

和本知识点经常一起出现的概念。