接口返回错误码，先把用户可处理的问题说清楚

接口返回错误码，先把用户可处理的问题说清楚

接口出错时，调用方通常只能看到状态码和一段提示。如果每个服务各写一套规则，排查会从“知道失败”变成“猜哪里失败”。设计错误码的重点，不是堆很多编号，而是让调用方知道能否重试、是否需要修改请求，以及应该把哪条信息交给运维。

先按处理动作分类

可以先把问题分成参数错误、身份与权限、资源状态、依赖服务和系统异常几类。参数错误通常需要调用方修改请求，重复提交没有意义；依赖超时可能适合有限次数重试；系统异常则应尽快告警并保留现场。分类先稳定下来，再为每类分配简短、可检索的业务码。

错误码和提示各司其职

错误码应保持稳定，文案可以更易读。返回内容至少说明业务码、面向用户的提示、请求追踪标识和必要的字段信息。不要把堆栈、SQL片段或内部地址直接返回给前端。字段错误可以指出字段名和修正方向，但要避免泄露敏感值。

把重试边界写进约定

对可能重复执行的请求，需说明幂等要求、退避建议和最大尝试次数。创建、扣减等操作应由服务端明确是否支持幂等键；查询类接口可以提示调用方稍后再试。这样客户端不会对所有错误统一重试，服务端也能减少无效流量。

用日志验证规则

上线前为每个重要错误码准备一条可复现的测试场景，检查响应码、业务码、提示和追踪标识是否一致。日志中记录业务码、接口名、请求标识和依赖耗时，监控按业务码聚合，而不是只统计500数量。规则稳定后，新服务接入时只需按约定补充具体码值。

一套好的错误码设计，最终服务于排查和协作。先定义处理动作，再约定返回字段和日志关联，接口出错时才不会让调用方只能反复试错。