API返回400/422错误时携带合法值列表是否是良好开发实践？

状态码选择 #

这种请求语法合法、仅业务语义不符合规则的场景，优先使用422 Unprocessable Entity而非400 Bad Request：

• 400 Bad Request一般用于请求格式错误场景，比如JSON语法非法、缺少必填的请求头/参数
• 422 Unprocessable Entity专门对应服务器可正常解析请求格式，但内容不符合业务约束的情况，和你的场景完全匹配

错误信息携带规则 #

返回状态码的同时携带具体错误说明、包括合法值列表，是非常推荐的良好实践，理由如下：

• 仅返回状态码的情况下，调用方无法定位具体错误原因，尤其是枚举值类的约束，不同开发/团队的认知可能存在偏差，没有明确提示的话需要额外查阅文档、甚至对接接口提供方，会大幅提升沟通和排查成本
• 枚举值数量较少的场景（比如你举例的只有2个合法值），直接把全部合法值附在错误提示里，调用方可以直接修正问题，不需要额外查资料
• 如果枚举值数量极多（超过20个），可以不用列全合法值，换成提示对应字段的枚举定义规则即可

推荐的响应结构 #

优先返回结构化的错误响应，方便人工排查也兼容程序自动处理，示例如下：

{
  "error_code": "INVALID_PARAM_VALUE",
  "message": "animal字段值非法",
  "invalid_field": "animal",
  "allowed_values": ["DOG", "CAT"]
}

如果不需要太复杂的结构，纯文本提示animal字段值非法，合法值为："DOG"、"CAT"也完全可以。

内容的提问来源于stack exchange，提问作者Alex Ferreira