API 是 21 世纪经济和我们日常生活中日益重要的一部分。 像 Stripe 和亚马逊这样的大公司都是建立在优秀的开发者平台上的。 甚至像办公电话系统这样的“模拟”工具也开始接触 API。 日益先进的 VoIP 产品集成 小型企业电话系统 使用 Google Workspace 等软件。 这为员工和客户带来了强大的新体验。 但 API 并不排除错误。 无论您是业余爱好者项目开发商还是百万美元 基于SaaS的产品 用户，你会发现故障是不可避免的。
什么是 API 错误/故障？
An API错误 发生 当服务器无法从 API 提供者处找到请求的资源时。在这种情况下，将返回数字错误消息以帮助识别特定错误。 API 错误的常见原因包括端点问题、参数不正确或请求调用期间 API 密钥问题。解决这些错误对于应用程序之间的无缝通信以及确保从 API 提供商成功检索数据至关重要。
6 个常见 API 错误
一些常见的 API 错误是：
HTTP/HTTPS 错误。
无用的 API 错误。
方法混淆。
缺少内容类型/接受标头。
授权错误。
数据格式错误。
1.HTTP/HTTPS错误
当 URL 中的 http:// 和 https:// 协议发生混淆时，就会出现最常见的 API 错误之一。
对于开发者来说，麻烦在于有些API仅支持HTTP协议，而另一些则兼容HTTPS。 有些在同一以客户为中心的产品中的不同端点支持不同的标准。
当开发人员将多个 API 串在一起时，这可能会变得更加混乱。 如果他们是内部开发人员，为与远程团队的异步业务通信构建“DIY”解决方案。 开发人员必须花时间定位导致问题的端点，然后创建解决方法以使两个 REST API 相互通信。
如果你是一个 API提供者，您可以通过制定特定的 HTTPS 策略来防止此错误。 例如，您可以让 API 在 HTTP 请求传入时自动将其重定向到 HTTPS 请求。
2. 无用的 API 错误消息
对于您的用户来说，错误消息的质量可能是短暂的打嗝和花费一个小时的时间的区别，这有助于 减少客户流失.
HTTP 提供了 70 多个 http 状态代码，但至少，您只需要实现开发人员习惯使用的最常见的代码。 其中的例子包括：
200 OK
都好！ 请注意，仅在一切实际情况下才提供此状态代码 is 好的。 众所周知，Facebook 的 Graph API 每当成功返回某些输出时都会提供 200 代码，即使该输出包含错误代码。
400错误请求
这几乎总是由于用户输入中的拼写错误造成的。 但这并不意味着您就可以摆脱困境！ 确保您的错误消息提供了有关错误输入的一些详细信息，以便用户可以快速修复它。
401未经授权
此状态表示输入正常，但用户的请求缺少授权码。 不要与…混淆
故宫403
这意味着授权代码被识别为有效，但用户没有权限。 例如，用户可能试图访问仅管理员可用的内容，这对远程工作人员来说是一个日益严重的安全问题。
404未找到
用户的请求有效，但他们请求的端点或资源不存在。 这可能是因为该文件已被删除，但请确保这不是由 HTTP/HTTPS 错误引起的。
429请求太多
当同一用户尝试快速连续多次调用 API 时，就会出现这种情况。 在过去十年中发生了多次备受瞩目的 DDoS 攻击之后，Web 服务正在密切关注谁访问其服务器以及访问频率。
这种速率限制与您在任何域或其他大型网站上发现的速率限制类似。 网页寄存服务 Cloudflare 等公司为其服务器上托管的域名提供 DDoS 保护。对于 API，这些保护必须是内置的。
5xx API 错误
以 5 开头的状态代码都是服务器错误，可能是您这边的错误。 如果是这种情况，请确保您的错误消息为用户提供一些帮助或保证。 这可以是联系信息或包含实时正常运行时间/停机时间信息的页面。
API 提供商只需进行一点定制和错误处理即可避免不良错误消息。 超越错误代码并使用链接回文档的清晰、简洁的消息。
软件提供商应该为将使用其 API 的开发人员创建目标消费者档案。 错误消息可以而且应该根据他们将要完成的数字任务类型进行定制。
查看来自 Twilio 的错误消息，其 API 允许开发人员拨打 VoIP 呼叫。
“`
{
“代码”：21211，
“message”: “‘收件人’号码 5551234567 不是有效的电话号码。”,
“more_info”：“https://www.twilio.com/docs/errors/21211”，
“状态”：400
}
“`
除了标准 400 状态之外，顶部还有一个自定义错误代码“21211”。 该消息甚至引用了导致问题的特定虚拟电话号码。 它引导用户访问其文档中讨论 21211 问题的页面。
对于试图将 API 集成到产品驱动型公司的开发人员来说，错误消息可能是一个巨大的绊脚石。 简单的集成过程对于 API 的成功至关重要。 许多人听到 Stripe 的第一件事就是，只需粘贴几行代码即可轻松进行付款。 因此，良好的错误消息不仅对于功能很重要，而且对于您的 API 来说也是一项重要的营销资产。
3. 方法混淆
当 API 及其用户混淆请求方法时，可能会遇到错误。 如果用户发送的 POST 请求被重定向并作为 GET 请求返回，则可能会导致令人沮丧的错误，而这并不是他们的错。
方法错误的另一个原因是文档不明确。 当文档的一部分没有解释需要哪些方法或完全使用错误的动词时，可能会发生这种情况。 （注意“get”和 GET 可以互换使用。确保文档的格式清晰，并为自己保留一封客户支持电子邮件。）
在几分钟内开发出强大且安全的 REST API
查看演示
4. 缺少 Content-Type/Accept 标头
大多数 API 调用至少有两个标头数据：Content-Type 和 Accept。 这些标头帮助两方（例如两个 API）协商发送哪种类型的数据以及将接受哪种类型的数据。 就像任何谈判一样，这些谈判也可能破裂。
如果没有理由如此严格，某些 API 将接受没有这些标头的请求。 每行代码都会向软件中引入可能的错误，因此云 PBX 提供商通常不会指定标头要求（如果不需要）。 但在存在安全问题的商业 API 中，开发人员会要求提供特定的 Content-Type 和 Accept 标头。 这使他们能够严格控制允许进入系统的内容以及允许通过的内容。
Content-Type 告诉 API 您发送的日期格式，Accept 告诉 API 发回的内容。 API 可能只需要您拥有 东西 在标头中，有些会接受特定类型并拒绝其他类型。
此信息应在文档中指定，这样做不会带来安全风险，但某些开发人员工具可能会让用户陷入困境。 考虑一下curl，它会自动在请求中包含默认的Accept 标头。 API 提供商可以预见这些工具异常，修改请求或发送特定的错误消息。
5. 授权错误
这是一种常见的 API 错误，而且通常非常简单。 使用 OAuth 2 安全协议的 API 需要额外的标头数据来处理请求。 这是“授权”标头，包含 API 处理请求所需的私钥。
发送“身份验证”标头是一个常见错误。 这是因为开发人员和文档经常互换地谈论身份验证和授权。 但即使标题被正确地标记为“授权”，令人困惑的格式错误也会让人感到困惑。
确保 OAuth 2 API 请求的格式如下，在私钥之前带有“Bearer”标志：
“`
授权：持有者 {your_api_key_here}
“`
用户名和密码对的格式应类似于“用户名：密码”。 但即使 API 请求不需要密码，用户也可能必须在末尾附加一个冒号。 API 提供者可以自己附加冒号，或者在文档中明确说明格式是什么。
6. 数据格式错误
即使用户做的一切都是正确的， APIs 仍然可以以错误的格式吐出数据。 如果 API 以 HTML 格式向用户提供数据，而不是他们认为自己要求的 JSON 数据，则可能会导致彻底崩溃。 更糟糕的是，他们的软件开发可能会愉快地接受数据并以意想不到的方式处理它。
如果开发人员尝试加入服务来衡量电子商务网站的转化率，营销团队将看不到代码。 他们可能会花几天时间查看错误数据，然后才有人意识到问题所在。
我们已经提到过，由于重定向，请求方法默认为 GET。 但更常见的是，当用户没有正确指定 Accept 标头（如果有的话）时，就会发生此错误。 这可能会让提供商有理由对他们接受的内容类型更加严格，即使这不是安全风险。
API 提供商还应该检查他们可能收到的默认响应或错误响应类型。 如果您的 API 没有理由处理 HTML，您应该拒绝该内容类型。 这可以避免您使用常用工具可能遇到的问题。 例如，每当 Nginx 遇到请求超时时，它都会给您一个 HTML 错误，而您的 API 不知道如何处理。
防止错误的解释
防止许多此类常见错误归结为彻底的测试。 一旦数据公开，严格控制 API 将接受的数据也是一个好主意。 此外，API 提供商应该重视优秀的 API 文档和错误消息。
这将帮助用户自己解决问题，但如果涉及到 客户服务软件，它将帮助您更快地解决问题。 一旦您发现了该缺陷，就该看看是否可以改进您的文档，甚至将整个问题抽象出来，以免再次发生。
了解快速、简单的端到端 API 管理
下载白皮书
作者： Astera 营销团队