REST API应用语义错误的HTTP响应状态码选型及通用处理问询

问题背景 #

现有一个电商平台商品库存更新的REST API，详情如下：

• URL：/products/stock
• 请求方法：PUT
• 请求体格式：

{
 "PRD001": 3,
 "PRD002": 2
}

请求体为<<PRODUCT_CODE>>:<<USER_REQUIRED_QUANTITY>>的键值映射结构。

服务器收到语法格式正确的请求，但会因以下应用语义逻辑失败：

1. 传入的一个或多个PRODUCT_CODE不存在；
2. 某PRODUCT_CODE对应的USER_REQUIRED_QUANTITY因库存不足无法满足。

针对这类应用语义错误，该REST API应返回何种HTTP状态码？个人初步观点如下：

• 不应返回400 - BAD REQUEST，因为请求语法格式合规；
• 产品编码不存在时不应返回404 - NOT FOUND，因为资源指向库存集合而非单个商品，易引发客户端误解；
• 可返回409 - CONFLICT（请求因与资源当前状态冲突无法完成）；
• 可返回422 Unprocessable Entity（服务器理解请求内容类型与语法，但无法处理），但该状态码属于WebDAV而非标准HTTP。

请教该特定场景的处理方案，以及通用场景下应用语义错误的HTTP状态码处理方式。

特定场景处理方案 #

针对该电商库存更新场景，推荐优先使用409 Conflict状态码，理由如下：

1. 库存不足场景：当前库存状态与请求要求的数量直接冲突，完全符合409的定义——请求无法完成是因为与目标资源的当前状态存在冲突；
2. 商品编码不存在场景：可将其视为请求引用了库存系统中不存在的资源，导致与系统当前状态（仅维护已知商品的库存）冲突，用409能合理覆盖该情况；
3. 相比422，409是标准HTTP状态码，兼容性更好，所有HTTP客户端都能正确识别。

同时，返回的响应体需明确给出错误细节，方便客户端定位问题，示例如下：

{
  "errors": [
    {
      "productCode": "PRD003",
      "message": "商品编码不存在"
    },
    {
      "productCode": "PRD001",
      "message": "库存不足，当前库存为1，请求数量为3"
    }
  ]
}

通用场景下应用语义错误的状态码选择 #

1. 409 Conflict：适用于请求与资源当前状态冲突的场景，比如库存不足、并发更新冲突、操作违反业务规则（如已下架商品无法修改库存）等；
2. 422 Unprocessable Entity：虽起源于WebDAV，但目前已被广泛接受为处理语义错误的状态码。当请求语法正确，但语义上无法处理时（如请求参数格式合法但不符合业务规则，例如年龄输入负数），可以使用。如果你的API生态系统普遍支持该状态码，也可作为备选；
3. 避免滥用400 Bad Request：400应仅用于请求语法错误（如JSON格式错误、参数类型不匹配），语义错误属于业务逻辑层面，用400会模糊错误类型，不利于客户端区分处理；
4. 避免滥用404 Not Found：404仅当请求的目标资源本身不存在时使用（如请求/products/PRD999这个不存在的商品），而批量库存更新的目标资源/products/stock是存在的，只是请求中的子引用无效，因此不适合用404。

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