API服务器与后端数据库连接超时，应返回何种HTTP响应码？

先明确两个候选状态码的适配性，再给出更贴合场景的方案：

408与429的语义匹配度分析 #

• 408 Request Timeout：HTTP标准定义中，该状态码用于「服务器等待客户端发送完整请求的时间超时」，本质是客户端到服务器的请求传输阶段出现问题。而你的场景是服务器内部与数据库的连接超时，属于服务器处理请求时的内部故障，用408会让客户端误解为自身请求发送过慢，不符合语义。
• 429 Too Many Requests：该状态码针对「单个客户端请求频率超出服务器限流规则」的场景。如果数据库连接超时是因某一个客户端短时间发送大量请求导致，用429合理；但如果是系统整体峰值负载（多客户端共同造成），这个状态码会误导客户端认为是自己请求过多，而非系统整体过载。

更推荐的状态码：503 Service Unavailable #

这个状态码的语义是「服务器暂时无法处理请求，可能因过载或维护导致」，完美匹配你的场景——峰值负载下数据库连接池耗尽，服务器暂时无法处理新请求。返回503时建议配合Retry-After响应头，告知客户端大致的重试间隔，示例响应如下：

HTTP/1.1 503 Service Unavailable
Retry-After: 60
Content-Type: application/json

{
  "error": {
    "code": "DatabaseConnectionTimeout",
    "message": "系统当前负载过高，数据库连接暂时不可用，请稍后重试。"
  }
}

额外优化建议 #

• 错误响应体中补充业务层面的明确信息，不要仅返回状态码，帮助客户端开发者快速定位问题原因。
• 针对这类数据库连接超时事件配置监控告警，方便运维团队及时排查峰值负载根源（比如连接池配置合理性、数据库扩容需求等）。

内容的提问来源于stack exchange，提问作者Murray Foxcroft