状态代码和错误代码是指响应头中的代码号，用于指示响应的常规分类，例如，请求是否成功（200），是否导致服务器错误（500），是否存在授权问题（403），等等。标准状态代码通常不需要太多文档，但是特定于您的API的自定义状态和错误代码则需要。错误代码特别有助于解决不良请求。

目录

• curl标头中的状态码示例
• 列出HTTP响应和错误码的位置
• 在哪里获取状态和错误码
• 如何列出状态码
• 状态/错误代码可以帮助进行故障排除
• 状态和错误码示例Context.ioTwitterMailchimpFlickr
• 具有状态和错误代码的活动

curl标头中的状态码示例

状态码未出现在响应正文中。它们显示在响应标题中，默认情况下您可能看不到。还记得您在“curl调用方法”中提交了curl调用吗？要获取响应头，请在curl请求中添加--include或-i。如果您只想在响应中返回响应标头（而不要返回其他任何内容），请大写-I，如下所示：

curl -I -X GET "https://api.openweathermap.org/data/2.5/weather?zip=95050&appid=fd4698c940c6d1da602a70ac34f0b147&units=imperial"

响应头如下所示：

HTTP/1.1 200 OKServer: openrestyDate: Thu, 06 Dec 2018 22:58:41 GMTContent-Type: application/json; charset=utf-8Content-Length: 446Connection: keep-aliveX-Cache-Key: /data/2.5/weather?units=imperial&zip=95050Access-Control-Allow-Origin: *Access-Control-Allow-Credentials: trueAccess-Control-Allow-Methods: GET, POST

第一行HTTP / 1.1 200 OK告诉我们请求的状态（200）。大多数REST API都遵循响应头的标准协议。例如，200不仅仅是OpenWeatherMap API开发人员确定的任意代码。200是用于成功HTTP请求的通用代码。（如果您更改方法，则会获得其他状态代码。）

有了GET请求，很容易判断请求是否成功，因为您会获得预期的响应。但是，假设您要进行POST，PUT或DELETE调用，那么您将在其中更改资源中包含的数据。您如何知道API是否成功处理并接收了请求？响应标头中的HTTP响应代码将指示操作是否成功。HTTP状态代码只是较长消息的缩写。

状态码通常不提供信息，编写得很差，并且很少或没有向用户传达有用的信息来克服该错误。最终，状态码应帮助用户从错误中恢复。

您可以在此处查看常见的REST API状态代码列表，并在此处查看HTTP状态代码的常规列表。尽管最好包含一些标准状态代码，但是不需要全面记录所有标准状态代码，尤其是在您的API很少触发的情况下。

列出HTTP响应和错误码的位置

大多数API应该有一个通用页面，其中列出了整个API的响应和错误代码。一个单独的页面列出了状态代码（而不是在每个端点中包括这些状态代码），使您可以更详细地扩展每个代码，而不会占用其他文档。它还减少了冗余和信息过载感。

另一方面，如果某些端点比其他端点更容易触发某些状态和错误代码，则在相同的API参考页面上突出显示这些状态和错误代码是有意义的。一种策略可能是引起注意特定端点的任何特别相关的状态或错误代码，然后链接到集中的“响应和状态代码”页面以获取完整信息。

在哪里获取状态和错误代码

在记录API时，状态代码和错误代码可能并不明显。您可能需要向开发人员索要API独有的所有状态和错误代码的列表。有时，开发人员会直接在编程代码中对这些状态和错误代码进行硬编码，而没有简单的方法来向您提供完整的列表（这也使本地化成为问题）。结果，您可能需要尝试一下以找出所有代码。

具体来说，您可能需要尝试破坏API才能查看所有潜在的错误代码。例如，如果您超出了特定呼叫的速率限制，则API可能会返回特殊错误或状态代码。您尤其需要记录此自定义代码。API中的疑难解答部分可能会特别使用错误代码。

如何列出状态码

您可以在基本表或定义列表中列出状态和错误代码，如下所示：

状态/错误代码可以帮助进行故障排除

状态和错误代码在进行故障排除时特别有用。因此，您可以将这些错误代码视为故障排除部分的补充。几乎所有的文档集都可以从故障排除一节中受益。

在故障排除主题中，您记录了当用户走开快乐的道路并在黑暗的森林中迷路时发生的情况。状态代码就像照明不佳的步道标志一样，可以帮助用户回到正确的道路上。

有关疑难解答的一节可能列出与以下情况有关的错误消息：

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

尽可能在文档中记录错误的确切文本，以便在搜索时轻松显示该错误。

状态和错误代码示例

以下是API文档中的一些示例状态和错误代码页。

Context.io

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

Twitter

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

这种有用的信息是技术作者应针对状态代码（至少对于那些指示问题的代码）的目标。

Mailchimp

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

Flickr

使用Flickr，“响应代码”部分嵌入在每个API参考主题中。因此，描述简短。在每个主题中嵌入响应代码会使错误代码更明显，但在某些方面却没有太大帮助。因为它嵌入在每个API主题中，所以有关错误代码的描述必须简短，否则内容将使端点请求信息不堪重负。

相比之下，列出错误代码的独立页面使您可以在不排挤其他文档的情况下更详细地扩展每个代码。独立页面还可以减少冗余并减少大量信息（只是重复的信息）的显示。

如果某些端点比其他端点更容易触发某些状态和错误代码，则在其相关的API参考页上突出显示这些状态和错误代码是有意义的。建议您注意端点页面上任何特别相关的状态或错误代码，然后链接到集中页面以获取完整信息。

具有状态和错误代码的活动

使用您确定的开源项目，确定状态和错误代码信息。回答以下问题：

• 项目是否描述状态和错误代码？状态和错误代码信息在文档上下文中位于何处？作为独立主题？在每个端点之下？别的地方？
• API是否具有任何唯一的状态和错误代码？
• 错误代码是否可以帮助用户从错误中恢复？
• 向其中一个端点发出请求。然后有意地更改参数，以使其无效。响应中返回什么状态码？是否记录了此状态码？