Rest 返回值

在 RESTful API 中，错误返回值通常是通过 HTTP 状态码 来表明请求的处理结果以及错误的原因。错误响应值包含状态码和消息描述，有助于客户端识别和处理错误。以下是常见的 REST 错误返回值及其含义：

1xx - 信息性状态码

信息性状态码通常在 RESTful API 中较少使用。

2xx - 成功状态码

这些状态码表明请求成功处理，通常不用于错误响应。

201 Created 是一个常见的 HTTP 状态码，表示请求已成功处理并且导致了新的资源的创建。它通常用于 POST 请求 或 PUT 请求，尤其是在客户端请求创建一个新资源时。

202 Accepted  表示请求已被接受，但尚未处理。这个状态码通常用于处理那些可能需要较长时间才能完成的操作。

204 No Content 状态码表明操作成功，但响应体为空，通常用于表示某个动作已经执行完毕，但没有需要返回的数据。

3xx - 重定向状态码

通常用于资源的重定向，较少用于错误响应。

4xx - 客户端错误状态码

这些状态码表示请求中存在客户端错误或请求不满足条件。常见的状态码有：

• 400 Bad Request
  表示请求格式不正确，服务器无法解析。
  示例：字段格式错误、缺少必填字段。

• 401 Unauthorized
  表示请求未通过认证，用户身份无法验证。
  示例：未提供有效的 API 密钥或令牌。

• 403 Forbidden
  表示用户已认证，但无权访问该资源。
  示例：用户尝试访问其权限范围外的数据。

• 404 Not Found
  表示请求的资源不存在。
  示例：客户端请求的 URL 或资源 ID 不存在。

• 405 Method Not Allowed
  表示资源不支持该请求方法。
  示例：在只允许 GET 请求的资源上使用 POST 方法。

• 406 Not Acceptable
  表示请求的内容格式不可接受。
  示例：客户端请求返回 XML 格式，但服务器只支持 JSON 格式。

• 409 Conflict
  表示请求与服务器上的资源产生冲突，通常是重复创建资源时出现。
  示例：尝试创建重复的唯一用户名或资源。

• 410 Gone
  表示请求的资源已被永久删除，不再可用。
  示例：请求已下线的资源。

• 415 Unsupported Media Type
  表示请求的媒体类型不支持。
  示例：服务器只接受 JSON 数据，但客户端发送的是 XML。

• 422 Unprocessable Entity
  表示请求格式正确，但无法被处理，通常是请求内容无效。
  示例：表单数据不符合验证规则，如无效的日期格式。

• 429 Too Many Requests
  表示请求过多，超过了限流阈值。
  示例：API 调用频率限制或限流策略生效。

5xx - 服务器错误状态码

这些状态码表示服务器端错误导致请求未完成：

• 500 Internal Server Error
  表示服务器发生未知错误，无法处理请求。
  示例：服务器代码异常、数据库连接失败。

• 501 Not Implemented
  表示服务器不支持请求的方法。
  示例：请求方法未在服务器端实现。

• 502 Bad Gateway
  表示服务器作为网关，接收到的响应无效。
  示例：服务器依赖的外部服务出错。

• 503 Service Unavailable
  表示服务器临时不可用，通常因过载或维护。
  示例：服务器因过载暂时停止服务。

• 504 Gateway Timeout
  表示服务器作为网关，等待外部服务响应超时。
  示例：服务器在调用第三方 API 时超时。

• 505 HTTP Version Not Supported
  表示服务器不支持请求使用的 HTTP 版本。

错误返回的最佳实践

1. 错误状态码：为不同的错误提供准确的 HTTP 状态码。
2. 错误消息：返回 JSON 格式的错误信息，如 "error": "Invalid user ID", 便于客户端解析。
3. 详细描述：添加 error_description 字段，以帮助开发者快速定位问题。