首次构建 API 时的 10 个错误状态代码以及如何修复它们

首次使用 API 时，特别是对于初学者，集成过程可能并不总是顺利。通常，文档可能对错误处理不够全面，因为预测问题的出现比预期顺利进行更具挑战性。

在 HTTP 中，许多状态代码可以帮助了解 API 调用中的问题。状态代码从 100 到 511，涵盖了不同的含义，其中 400 到 511 之间的代码涉及错误。可以通过下面的表格查看这些状态代码。

接下来，我们将介绍 10 个常见的 HTTP 状态代码，它们表示客户端或服务器上的错误。

客户端错误

状态代码 4XX 通常与客户端错误有关，但 API 的更改也可能引发这些错误。以下是 5 个常见的错误及其解决方法：

404 未找到

这是最常见的错误代码，表示请求的 URL 在服务器上不存在。这通常指示客户端的错误，但有时也可能是服务器端的问题，例如 API URL 在版本更新后发生更改。建议首先检查客户端代码中的拼写错误，然后再检查 API 是否存在问题。

401 未经授权

此状态代码表示未进行身份验证。API 无法识别用户，因此无法提供服务。通常，您需要注册并获取 API 密钥，并在请求时通过 HTTP 标头传递该密钥，以便 API 知道您的身份。

403 禁止访问

“禁止”状态表示您无权访问请求的 URL。与“未经授权”不同的是，您已经通过身份验证，但当前用户或角色不允许访问该资源。这可能由于使用错误的 API 密钥或尝试访问未授权的功能而发生。

400 错误请求

这是一个通用错误消息，表示请求中存在问题。如果响应正文没有提供更多信息，需检查文档。可能是请求中缺少必要的查询或正文字段，标头设置错误，或请求数据格式不正确。

429 请求过多

许多 API 订阅计划对请求数量有限制。较便宜的计划通常允许的请求次数较少。如果短时间内发送了过多请求，请考虑在客户端限制请求频率。这种状态也可能表示已达到每日、每周或每月的限制。在集成 API 之前，建议检查订阅计划中的限制，以避免在集成后遇到问题。

服务器端错误

状态代码 5XX 通常与服务器端错误有关，但如果服务器未正确处理应返回 4XX 响应的无效请求，也可能导致 5XX 错误。以下是 5 个常见的错误及其解决方法：

500 内部服务器错误

该状态通常表示 API 服务器出现故障或崩溃。可能与请求相关的某些内容引起了问题。建议仔细检查文档，确认请求的查询字段、正文字段、标头、格式等都正确。如果问题依旧，可能与 API 更新中的错误代码或从上游服务加载的数据有关。这种情况下，联系 API 支持是唯一的解决办法。

502 错误网关

此状态表明调用的服务器是网关或代理，而不是实际的 API 服务器。代理服务器尝试代表客户端调用 API 服务器，但 API 服务器未响应。这可能与网络问题有关，也可能是 API 服务器崩溃或因维护而停机。通常，这种问题是暂时的，应由 API 提供商解决。如果问题持续存在，则需联系支持人员。

503 服务不可用

此状态表示服务器过载，无法处理更多请求。通常是因为发送了过多的 API 请求。如果客户端减少请求数量，问题通常会自行解决，但也可能表明 API 提供商未为所有客户分配足够的资源。可以通过调整请求频率来应对此错误。如果错误频繁出现，则需要联系 API 提供商。

504 网关超时

此状态表示代理服务器在预定时间内未能从实际的 API 服务器收到响应。可能由于代理和 API 服务器之间的高网络延迟，或 API 服务器处理请求所需时间过长。检查请求内容是否可能导致超时，例如请求的数据量过大或计算复杂度过高。如果请求合理且问题依旧，请联系支持人员。

501 未实施

该状态表示请求的 HTTP 方法尚未实现。通常，错误的方法请求会导致 404 未找到状态。未实施状态表示 API 创建者可能计划在未来实现该方法。尝试其他方法可能会获得更好的结果。

监控 HTTP 错误代码

手动跟踪这些错误很快就会变得繁琐且容易出错。

API 分析工具可以提供监控和通知功能，自动报告任何 HTTP 状态码错误，并从错误状态码的趋势中获得深入洞察。这些工具可以是内部开发的，也可以是购买的。以下是一个 API 分析工具的示例，它记录了 HTTP 错误随时间变化的趋势。

如果分析工具使用用户身份跟踪 API 调用，则可以更轻松地定位问题并快速解决问题。

总结

毫无疑问，使用 API 时会遇到许多错误代码，但大多数都有合理的解决方法。这些错误可能与服务器端问题有关，也可能与客户端问题有关，并且一个错误通常会导致另一个错误。

始终尽量彻底阅读文档，以确保在集成时不会遗漏任何重要信息。如果遇到的问题不多，可以联系 API 提供商寻求帮助。

在某些情况下，API 提供商可能无法解决问题，这时需要找到替代解决方案。如果使用的是流行的 API，可以通过网络搜索，尤其是在 StackOverflow 上，寻找解决问题的方法。

原文链接：10 Error Status Codes When Building APIs for the First Time and How To Fix Them