Question

API错误代码响应模式的最佳选择是什么？

不是使用表示不同类型错误的不同代码

100001 // username not provided
100002 // password not provided
100003 // password too short
...

我看到一些other use patterns，如下所示（非顺序）...

还有其他建议吗？

Answer 1

IETF（互联网标准组织）的建议是使用application / problem + json媒体类型。

值得注意的是，它们不使用随机数，而是使用字符串（特别是uris）来识别错误。

这是一个主观的问题，但是即使您不使用其格式，我也会认为username-not-provided几乎在所有方面都优于100001。

Answer 2

根据我开发和使用Web服务的经验，我发现结合使用顶级HTTP状态代码和更低级API错误代码的策略相当有效。请注意，较低级别的API错误代码不必是整数，而可以是任何枚举。对于一个众所周知的公共示例，AWS简单电子邮件服务（SES）使用此strategy of using both HTTP status codes and API level error codes。您可以看到一个sample error code response for SES here。请注意，尽管SES使用XML响应错误有效负载，但该策略对JSON响应有效负载同样有效。

根据我的经验，使用此策略时需要牢记以下几点：

力争返回正确的HTTP响应代码： HTTP是一个普遍存在的协议，毫无疑问您的Web容器可以理解。它的响应代码自然适合REST Web服务。因此，利用它！如果您的Web服务遇到错误情况，则应尽力返回正确的HTTP状态代码，在该上下文中，API错误代码具有含义。开发人员只是无条件地将任意（通常是运行时）异常备份到堆栈中，这是我调试Web服务问题时最大的头痛。结果是，即使不是这种情况，所有内容都以HTTP 500（内部服务器错误）状态代码返回给调用方（例如，客户端发送垃圾数据，而服务器无法处理它。一些常见的HTTP状态代码）您可能想要设计包括：
- 400错误的请求：客户的请求有问题。请注意，此错误不仅用于诸如POST请求中的JSON语法损坏之类的错误，而且还用于it is also a legitimate response code for semantic issues as well（即JSON请求有效负载符合规定的架构，但是有效负载中的数据存在问题，例如表示应该为正数时为负数。
- 401未经授权：呼叫者的凭据无效（即授权错误）。
- 403禁止访问：呼叫者的凭据有效，但是其访问级别不足以访问资源（即身份验证错误）。
- 404找不到： URL的资源不存在。
- 500内部服务器错误：服务器本身内部发生了一些错误，此错误可能是任何原因。
- 502错误的网关：调用下游服务时发生错误。
- 503服务不可用：一个有用的响应代码，当您遇到大量无意间使用DDOS服务的“快乐”客户时，会感到不满意。
- 504网关超时：类似于502状态码，但指示超时，而不是下游服务本身的实际错误。
HTTP响应代码是顶级代码，API错误代码仅在该上下文中具有含义： 意思是，这意味着您的API错误代码仅是对于某些HTTP响应代码有意义。例如，在table of SES error codes中，每个错误代码仅绑定到一个HTTP（S）响应代码。错误代码ConfigurationSetDoesNotExist和InvalidParameterValue仅在SES返回400 Bad Request时才有意义-在返回500 Internal Server Error时返回这些状态码是没有意义的。同样，如果您正在编写一个称为下游服务和数据库的Web服务，则可能会有一个FooDownstreamServiceTimedOut错误代码，当下游Web服务调用超时时，您将返回一个504 Gateway Timeout HTTP状态代码。 “ Foo” Web服务。您可能还具有一个MyDatabaseError错误代码，当您对内部数据库的查询失败时，将返回一个500 Internal Server Error HTTP状态代码。
具有统一的错误代码架构，而与状态代码无关： ：您的客户需要能够以编程方式处理您的错误内容。因此，它需要符合特定的架构。理想情况下，您的API错误代码架构应包含错误代码（即名称或ID等）。您可能还希望包括错误代码的自然语言描述以及您正在响应的请求的ID / GUID。有关错误模式的示例，请参见this sample AWS SES response and schema。此外，您可能还需要考虑在响应中返回客户端ID。与客户一样，这对您自己也有好处，因为它可以帮助您向下钻取数据，以查看一个特定的客户端相对于其他客户端是否有大量的特定错误。
考虑在响应中返回错误代码的自然语言描述： 为了使您的客户更轻松，您可能需要考虑不只是返回以下内容中的错误代码：错误有效载荷，但自然语言描述也是如此。这种行为可以立即帮助那些实际上不太在乎您的服务的困惑和忙碌的工程师迅速诊断正在发生的事情，以便他们可以尽快解决问题。顺便说一句，使工程师能够快速诊断您的服务问题增加了您的客户和经理无疑会关心的至关重要的“正常运行时间”指标。
不必强迫使用整数，而应使用枚举： “错误代码”的概念会让人联想到过时的技术和密码本错误是什么意思。它源于编程时代的黑暗时代，当时工程师需要将所有可能的错误放入一个字节的空间中，或半字节或其他任何形式。那些日子已经一去不复返了，您的错误代码可能是字符串，可能对性能没有任何有意义的影响。您也可以利用它并使错误代码有意义，以使事情保持简单。
将可能需要调试但要注意安全性的信息返回给客户端： ：如果可能，返回客户端可能需要的任何调试信息。但是，如果您的服务可能处理诸如信用卡号之类的敏感信息，则您可能出于明显的原因不希望传递该信息。

希望有帮助。

Answer 3

我会说这在很大程度上取决于您提供的是哪种API。

我总是在每个响应中都包含一个名为ack的字段，该字段具有以下三个状态：failure，warning，success。成功显然是一切顺利。在发出警告时，请求将通过，并且JSON将包含预期的输出，但它还将包含一个warning字符串，甚至在出现多个警告的情况下更好，该数组称为errors，该数组包含多个包含code，string和type的对象。在failure的情况下，也将返回此数组，除了此数组之外，什么也没有。

该数组在每个错误或警告中包含一个对象，具有一个代码（我建议您以最初的想法10001、10002 ... ...）和一个用短短语解释错误的字符串（例如{{1 }}）。 Username contains invalid characters是type或error，在warning确认不仅包含错误而且包含警告的情况下很有用。

这使得通过错误代码查找错误变得容易（我将提供一个页面，同时提供一个API，该页面包含表中的所有错误代码以及它们的简短描述，简短描述以及常见原因/解决方案/等。 -所有这些信息也应该可以通过API获得，通过提供错误代码可以访问它们，同时仍然可以快速获得简短的文本响应，以便用户可以在大多数情况下指出问题所在而无需查找错误。

这还允许将警告和错误轻松输出给最终用户，而不仅仅是开发人员。通过将我的想法与API调用结合使用来获取有关错误的信息，使用API的开发人员可以在需要时轻松地向最终用户提供有关错误的完整信息（包括原因/修复程序/只要您认为合适）。

Answer 4

不是从头开始编写自己的API标准，而是采用一种已经可用的标准，例如JSON API标准：

如果您曾与您的团队就JSON响应的格式化方式进行过辩论，那么JSON API可以成为您的防垃圾邮件工具。

通过遵循共享约定，您可以提高生产力，利用通用工具并专注于重要的事情：您的应用程序。

围绕JSON API构建的客户端能够利用其功能有效地缓存响应，有时甚至完全消除了网络请求。

如果您决定使用JSON API，它将具有a section dedicated to errors和a few error examples。

Answer 5

多年来，许多发达的公司都为错误创建了诸如位掩码之类的东西，因此它们可以在错误内部编码多个变量：

000 - all ok
001 - something failed with X
010 - something failed with Y
011 - something failed with X and Y
100 - something failed with Z
101 - something failed with X and Z

限制是将错误空间限制为您决定编码的字节数，例如16或32个可能的组合，对于您而言是否足够？

您看到这在COM +中很常见 https://docs.microsoft.com/en-us/windows/desktop/com/com-error-codes-1

我希望这会有所帮助。

API的错误代码模式

5 个答案: