API 接口返回码
一、常见返回码分类及含义
| 返回码类型 | 描述 | 示例 |
| 成功类返回码 | 表示请求已成功处理，数据已正确返回或操作已成功执行。 | 200 OK：请求成功，服务器成功返回所请求的资源，且资源内容在响应体中，客户端向服务器请求获取某个用户信息，若用户存在且服务器正常返回该用户详细信息，通常会返回 200 状态码。 201 Created：请求成功并且服务器创建了新的资源，比如在博客系统中，用户发布一篇新文章后，服务器成功创建该文章资源并返回 201 状态码，响应体中可能包含新文章的 ID 等相关信息。 204 No Content：请求成功，但服务器没有内容可返回，常见于 PUT 或 DELETE 操作成功后，不需要返回具体资源内容时，更新一个用户的密码，操作成功后，服务器返回 204 状态码，表示密码已更新且无需额外返回信息。 |
| 客户端错误类返回码 | 主要由于客户端请求存在问题导致服务器无法正常处理。 | 400 Bad Request：错误的请求，服务器无法理解客户端发送的请求，请求参数格式错误（如日期格式应为“YYYY-MM-DD”，但客户端传入“DD-MM-YYYY”）、缺少必要的请求参数等情况，服务器会返回 400 状态码。 401 Unauthorized：未授权，表示客户端未提供有效的身份验证凭据或凭据无效，比如在访问需要登录才能查看的用户个人资料页面时，如果用户未登录或提供的用户名和密码错误，服务器将返回 401 状态码。 403 Forbidden：禁止访问，客户端虽然提供了身份验证凭据，但无权访问请求的资源，普通用户尝试访问管理员专属的功能页面，即使已登录，服务器也会返回 403 状态码拒绝访问。 404 Not Found：资源未找到，服务器无法找到客户端请求的资源，如请求一个不存在的商品详情页 URL，服务器会返回 404 状态码。 |
| 服务器错误类返回码 | 表明服务器在处理请求过程中出现问题。 | 500 Internal Server Error：服务器内部错误，服务器在处理请求时遇到意外情况，无法完成请求，这可能是由于服务器代码逻辑错误、数据库连接异常等原因导致，服务器在查询数据库时突然与数据库失去连接，无法获取所需数据来响应客户端请求，此时会返回 500 状态码。 502 Bad Gateway：无效网关，通常出现在服务器作为网关或代理时，从上游服务器收到无效响应，比如在微服务架构中，API 网关转发请求到后端服务时，后端服务出现故障返回无效响应，网关就会向客户端返回 502 状态码。 503 Service Unavailable：服务不可用，服务器当前无法处理请求，可能是由于服务器维护、过载等原因，服务器正在进行系统升级维护，暂时停止对外提供服务，此时对所有接收到的请求都会返回 503 状态码。 504 Gateway Timeout：网关超时，服务器作为网关或代理时，等待上游服务器响应超时，假设 API 网关向后端服务转发请求后，长时间未收到后端服务的响应，超过设定的超时时间后，网关就会向客户端返回 504 状态码。 |
二、HTTP 状态码与方法的关联
不同的 HTTP 方法在特定场景下可能会对应不同的常见返回码，以下是一些示例：
|HTTP 方法|可能的返回码|场景描述|
|—-|—-|—-|
|GET|200 OK|请求的资源正常存在并被成功获取，如获取网页内容、查询数据库中的某条记录等。<br>404 Not Found|请求的资源路径错误或资源已被删除，服务器上找不到对应的资源。<br>500 Internal Server Error|服务器在处理 GET 请求过程中出现内部错误，如数据库查询语句错误导致无法正常获取数据。|
|POST|201 Created|成功创建新资源，如在论坛上发表新帖子后，服务器返回新帖子的创建信息及相关状态码。<br>400 Bad Request|提交的数据格式有误或缺少必要字段，例如注册新用户时，密码格式不符合要求或未填写用户名。<br>503 Service Unavailable|服务器因过载或维护等原因无法处理新资源的创建请求。|
|PUT|200 OK|资源更新成功，例如修改用户资料后，服务器返回更新成功的信息及状态码。<br>403 Forbidden|用户没有足够的权限去更新特定资源，比如普通用户尝试修改管理员设置的系统参数。<br>502 Bad Gateway|在分布式系统中，更新请求经过多个中间环节时，某个中间环节出现故障导致更新失败并返回此状态码。|
|DELETE|204 No Content|资源删除成功且无需返回具体资源内容，如删除一条订单记录后，服务器仅表明删除操作已完成。<br>404 Not Found|要删除的资源本身就不存在，所以无法执行删除操作。<br>500 Internal Server Error|服务器在执行删除操作时内部出现错误，如数据库删除语句执行失败。|
三、相关问题与解答
问题 1：为什么有时候服务器会返回 504 Gateway Timeout，而不是直接返回 500 Internal Server Error？
解答：504 Gateway Timeout 和 500 Internal Server Error 都表示服务器端出现了问题，但它们有不同的侧重点，504 Gateway Timeout 特指服务器作为网关或代理时，等待上游服务器响应超时的情况，这意味着服务器本身可能是正常的，但在与其他服务器（上游服务器）通信协作过程中出现了延迟过高或无响应的问题，而 500 Internal Server Error 是一个更广泛的服务器内部错误标识，它涵盖了服务器自身在处理请求时的各类意外情况，如代码逻辑错误、内存不足、数据库连接异常等，不一定是因为等待其他服务器响应导致的，所以当问题明确是由于等待上游服务器超时时，会返回 504 状态码；如果是服务器自身原因导致无法处理请求，则可能返回 500 状态码。
问题 2：客户端收到 400 Bad Request 返回码后，应该如何处理？
解答：当客户端收到 400 Bad Request 返回码后，首先应该仔细检查发送的请求，查看请求的 URL 是否正确，包括路径和查询参数是否符合 API 的要求；检查请求头中的信息是否完整且格式正确，Content-Type 头是否设置为 API 期望的值；对于 POST 或 PUT 等需要提交数据的请求方法，要认真核对请求体中的数据格式是否符合规定，是否包含所有必要的字段且字段值是否符合业务规则，根据具体的错误提示信息进行相应的修改后重新发送请求，如果不确定问题所在，可以查阅 API 文档或联系 API 提供方获取更详细的指导。
以上内容就是解答有关“api接口返回码”的详细内容了，我相信这篇文章可以为您解决一些疑惑，有任何问题欢迎留言反馈，谢谢阅读。
【版权声明】：本站内容若无意侵犯到您的权利，请及时与我们联系将尽快删除相关内容!
