API状态和错误码( 二 ) _API

文章插图

状态/错误代码可以帮助进行故障排除状态和错误代码在进行故障排除时特别有用。因此，您可以将这些错误代码视为故障排除部分的补充。几乎所有的文档集都可以从故障排除一节中受益。
在故障排除主题中，您记录了当用户走开快乐的道路并在黑暗的森林中迷路时发生的情况。状态代码就像照明不佳的步道标志一样，可以帮助用户回到正确的道路上。
有关疑难解答的一节可能列出与以下情况有关的错误消息：

使用了错误的API密钥
使用了无效的API密钥
参数不适合数据类型
API引发异常
没有数据可返回的资源
已超出速率限制
参数超出了可接受的最大值和最小值范围
端点缺少必需的参数

尽可能在文档中记录错误的确切文本，以便在搜索时轻松显示该错误。
状态和错误代码示例以下是API文档中的一些示例状态和错误代码页。
Context.io

文章插图
Context.io状态和错误代码
Clearbit不仅记录了标准状态码，而且还描??述了其API返回的唯一参数。大多数开发人员可能会熟悉200、400和500的代码，因此这些代码不需要太多解释性的细节。但是，如果您的API具有唯一的代码，请确保充分描述它们。
Twitter

文章插图
Twitter状态和错误代码
借助Twitter的状态代码文档，他们不仅可以描述代码和状态，还可以提供有用的故障排除信息，从而可能有助于错误恢复。例如，对于500错误，作者不只是说状态是指服务中断，他们还解释说：“这通常是暂时的错误，例如在高负载情况下，或者端点暂时有问题。如果其他人遇到类似问题，请登录开发者论坛，或者稍后再试。”
这种有用的信息是技术作者应针对状态代码（至少对于那些指示问题的代码）的目标。
‌
Mailchimp

文章插图
Mailchimp状态和错误代码
Mailchimp提供了错误消息的可读且友好的描述。例如，对于403错误， Mailchimp不仅仅是写“ Forbidden” ，还解释了为什么您可能会收到Forbidden代码的原因。使用Mailchimp ，有几种类型的403错误。您的请求可能由于用户帐户被禁用或对错误的数据中心的请求而被禁止。对于“ WrongDataCenter”错误， Mailchimp指出“它通常与配置错误的库相关联” ，并且它们链接到有关数据中心的更多信息。这是对用户有用的错误代码文档。
‌
Flickr

文章插图
Flickr的状态和错误代码
使用Flickr ， “响应代码”部分嵌入在每个API参考主题中。因此，描述简短。在每个主题中嵌入响应代码会使错误代码更明显，但在某些方面却没有太大帮助。因为它嵌入在每个API主题中，所以有关错误代码的描述必须简短，否则内容将使端点请求信息不堪重负。
相比之下，列出错误代码的独立页面使您可以在不排挤其他文档的情况下更详细地扩展每个代码。独立页面还可以减少冗余并减少大量信息（只是重复的信息）的显示。
如果某些端点比其他端点更容易触发某些状态和错误代码，则在其相关的API参考页上突出显示这些状态和错误代码是有意义的。建议您注意端点页面上任何特别相关的状态或错误代码，然后链接到集中页面以获取完整信息。
具有状态和错误代码的活动使用您确定的开源项目，确定状态和错误代码信息。回答以下问题：