WebAPI认证接口最佳实践：200与401返回码使用疑问

这是个非常贴合API最佳实践的问题，我在设计认证相关接口时也反复确认过这个点，结论很明确：当用户名或密码无效时，返回401 Unauthorized是最符合HTTP语义规范的选择。

为什么选401而不是其他状态码？ #

• 从HTTP标准定义来看，401的核心语义就是「请求需要用户身份验证」，当传入的凭证（用户名/密码）无效时，本质上就是身份验证失败，完全匹配这个场景。
• 别混淆403 Forbidden：403的语义是「服务器理解请求，但拒绝执行」，通常用于用户已通过认证，但没有权限访问目标资源的场景，和认证失败是完全不同的两个阶段，这里用403会让客户端混淆逻辑。
• 其他状态码比如400 Bad Request并不合适：400一般用于请求格式错误（比如JSON格式非法），而凭证无效是业务逻辑层面的认证失败，不属于请求格式问题。

额外的最佳实践建议 #

• 返回401时，建议在响应头中添加WWW-Authenticate字段，比如：

  WWW-Authenticate: Bearer realm="YourAPIRealm"
  

  这是HTTP规范的要求，虽然JWT场景下客户端大概率知道认证方式，但遵循规范能让API更严谨，也方便一些通用的HTTP客户端库处理。
• 在响应体中返回清晰的错误信息，比如：

  {
    "error": "InvalidCredentials",
    "message": "用户名或密码无效，请重新输入"
  }
  

  这样客户端能快速定位问题，也便于调试。

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