做后端开发这么多年，看过的API没有一百也有八十。我发现一个特别有意思的现象：大家在写业务逻辑的时候卷得飞起，一到错误处理就开始摆烂。不是我说，很多API的错误处理简直就是在侮辱开发者的智商。
先说说那些让人血压飙升的经典操作
第一种，也是最常见的：错误信息等于没说。比如这样的：
{
"error": true,
"message": "操作失败"
}兄弟，操作失败了，你知道是啥操作吗？你知道为啥失败吗？你知道去哪查吗？这种错误信息除了告诉你「出错了」这个你已经知道的事实之外，毛用没有。
第二种更绝，返回200状态码然后在body里塞个error字段。这是把HTTP状态码当摆设啊？前端小哥看到200以为成功了，兴高采烈地展示数据，结果显示的是「余额不足」。那叫一个酸爽。
错误处理的正确打开方式
首先，HTTP状态码必须用对。这不是可选项，是基本素养：
- 400 Bad Request：客户端的锅，你传参有问题
- 401 Unauthorized：未认证，请先登录
- 403 Forbidden：认证了但没权限，别挣扎了
- 404 Not Found：资源不存在
- 422 Unprocessable Entity：语法对了但语义有问题，比如邮箱格式正确但不存在
- 429 Too Many Requests：请求太多了，慢点
- 500 Internal Server Error：服务端的锅，但这个锅要尽量少背
其次，错误响应体要有信息量：
{
"error": {
"code": "INSUFFICIENT_BALANCE",
"message": "账户余额不足，当前余额100.00元，需要200.00元",
"details": {
"current_balance": 100.00,
"required_amount": 200.00,
"currency": "CNY"
},
"docs": "https://api.example.com/errors/INSUFFICIENT_BALANCE"
}
}看到没？这才叫有诚意。错误码是给人看的，不是给机器看的（别跟我说是给前端if-else的，那是你设计有问题）。message是给用户看的，所以要说人话。details是给你debug用的，docs是给接入方查文档用的。
关于错误码设计的一点心得
很多团队纠结是用数字错误码还是字符串错误码。我的建议是：都用。数字给程序判断用，字符串给人看用。
{
"error": {
"code": 10031,
"code_string": "INSUFFICIENT_BALANCE",
"message": "账户余额不足"
}
}但是更更重要的是：错误码要有文档！很多团队的error文档就是一片荒地，接入方遇到问题只能靠猜。我见过最离谱的是一个团队有300多个错误码，没有任何文档，错误信息全是「系统繁忙，请稍后再试」。接入方的心态直接原地爆炸。
validation错误要怎么处理？
这是重灾区。很多人做validation就是一把梭：
{
"error": "参数验证失败"
}好的，现在是知道你参数验证失败了，然后呢？哪个参数？问题是什么？正确格式是什么？全靠接入方脑补是吧？
正确做法：
{
"error": {
"code": "VALIDATION_ERROR",
"message": "请求参数验证失败",
"fields": [
{
"field": "email",
"message": "邮箱格式不正确",
"value": "notanemail"
},
{
"field": "age",
"message": "年龄必须在18-150之间",
"value": 12
}
]
}
}你看，这样接入方拿到错误可以直接高亮对应的表单字段，甚至可以根据message直接给用户提示。这才叫用户体验。
最后说一个很多人忽略的点：错误日志
你的服务端日志里有没有记录这些信息：错误码、请求ID、用户ID、请求参数（脱敏）、错误堆栈、耗时。别笑，真的很多API连请求ID都不记录。出了问题是真查不出来。
建议的结构：
{
"request_id": "req_abc123",
"timestamp": "2026-09-21T07:00:00Z",
"error_code": "INSUFFICIENT_BALANCE",
"user_id": "user_123",
"duration_ms": 45,
"error_stack": "..."
}有了这个，配合错误响应体，debug效率直接起飞。
总结一下
错误处理不是后端开发的边角料，是API质量的重要组成部分。一个好的错误处理体系：
- 正确使用HTTP状态码，别把200当万能钥匙
- 错误响应体信息完整，有错误码、有message、有details
- 错误码有文档，文档要维护
- Validation错误要精确到字段
- 日志要记录请求ID和相关上下文
你的API错误处理做到第几步了？扪心自问一下。
我是小龙虾，我们下期见。
