API 的错误代码模式

API错误代码响应模式有哪些好的选择？

而不是使用不同的代码来指示不同类型的错误

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

我看到一些其他使用模式 https://support.multiplay.co.uk/support/solutions/articles/1000128432-why-does-my-card-keep-getting-declined-像下面这样（非顺序）...

20000
20001
20004
20015

还有其他建议吗？

根据我开发和使用 Web 服务的经验，我发现以下策略使用顶级 HTTP 状态代码和较低级别 API 错误代码的组合效果相当好。请注意，较低级别的 API 错误代码不需要是整数，而是可以是任何枚举。对于一个众所周知的公共示例，AWS Simple Email Service (SES) 使用此同时使用 HTTP 状态代码和 API 级别错误代码的策略 https://docs.aws.amazon.com/ses/latest/DeveloperGuide/api-error-codes.html。你可以看到一个SES 的示例错误代码响应此处 https://docs.aws.amazon.com/ses/latest/DeveloperGuide/query-interface-responses.html。请注意，尽管 SES 使用 XML 响应错误负载，但此策略同样适用于 JSON 响应负载。

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

1. Strive to return the correct HTTP response code: HTTP is a ubiquitous protocol and is no doubt understood by your web container. Its response codes fit naturally into REST web services. As such, leverage it! If your web service encounters an error condition, you should do your best to return the correct HTTP status code in whose context, the API error code has meaning. One my biggest headaches in debugging issues with web services occur when developers just unconditionally throw arbitrary (usually runtime) exceptions back up the stack. The result is that everything gets returned back to the caller as an HTTP 500 (Internal Server Error) status code even when that's not the case (e.g. the client sends garbage data and the server just can't process it. Some common HTTP status codes you might want to design for include:
   • 400 错误请求：客户的请求有问题。请注意，此错误不仅用于 POST 请求中损坏的 JSON 语法之类的情况，还用于它也是语义问题的合法响应代码 https://stackoverflow.com/a/20215807/4851565（即 JSON 请求有效负载符合规定的架构，但有效负载中的数据存在问题，例如本应为正数的数字却为负数）。
   • 401 未经授权：调用者的凭据无效（即授权错误）。
   • 第403章 禁止：调用者的凭据有效，但其访问级别不足以访问资源（即身份验证错误）。
   • 404 未找到：URL 的资源不存在。
   • 500内部服务器错误：服务器本身内部发生了一些不好的事情，这个错误可能是任何错误。
   • 502错误的网关：调用下游服务时发生错误。
   • 503服务不可用：当您受到大量无意中对您的服务进行 DDOS 攻击的“满意”客户的打击时，这是一个有用的响应代码。
   • 504网关超时：与 502 状态代码类似，但表示下游服务本身超时而不是实际错误。
2. HTTP 响应代码是顶级代码，API 错误代码仅在该上下文中有意义：我的意思是，您的 API 错误代码仅对某些 HTTP 响应代码有意义。例如，在SES 错误代码表 https://docs.aws.amazon.com/ses/latest/DeveloperGuide/api-error-codes.html，每个错误代码仅与单个 HTTP(S) 响应代码相关联。错误代码ConfigurationSetDoesNotExist and InvalidParameterValue只有当400 Bad Request由 SES 返回 - 当 a 时返回这些状态代码是没有意义的500 Internal Server Error被返回。同样，如果您正在编写一个调用下游服务和数据库的 Web 服务，您可能有一个FooDownstreamServiceTimedOut您将返回的错误代码504 Gateway Timeout当下游 Web 服务调用“Foo”Web 服务超时时的 HTTP 状态代码。您可能还有一个MyDatabaseError您将返回的错误代码500 Internal Server Error对内部数据库的查询失败时的 HTTP 状态代码。
3. 无论状态代码如何，都有统一的错误代码架构：您的客户需要能够以编程方式处理您的错误内容。因此，它需要符合一定的模式。理想情况下，您的 API 错误代码架构应包含错误代码（即名称或 ID 等）。您可能还希望包含错误代码的自然语言描述以及您正在响应的请求的 ID/GUID。有关错误模式的示例，请参阅此示例 AWS SES 响应和架构 https://docs.aws.amazon.com/ses/latest/DeveloperGuide/query-interface-responses.html。此外，您可能还需要考虑在响应中返回客户端 ID。这既符合您自己的利益，也符合客户的利益，因为它可以帮助您深入研究数据，看看某个特定客户与其他客户相比是否出现了过多的特定错误。
4. 考虑在响应中返回错误代码的自然语言描述：为了让您的客户端更轻松，您可能不仅需要考虑返回错误负载中的错误代码，还需要考虑自然语言描述。这种行为可以立即帮助那些真正不太关心您的服务的困惑而忙碌的工程师快速诊断发生的情况，以便他们能够尽快解决问题。顺便说一句，使工程师能够快速诊断您的服务问题会增加您的客户和经理无疑会关心的最重要的“正常运行时间”指标。
5. 不要觉得有必要使用整数，而是使用枚举：“错误代码”的概念让人想起过时的技术和密码本，您必须在其中查找错误的含义。它起源于编程黑暗时代，当时工程师需要将所有可能的错误放入一个字节的空间，或半字节或其他任何东西中。那些日子已经一去不复返了，你的错误代码可以是一个字符串，可能不会对性能产生任何有意义的影响。您不妨利用并使错误代码有意义，作为使事情变得简单的一种方法。
6. 将他们可能需要调试的信息返回给客户端，但要注意安全性：如果可能，返回客户可能需要的任何调试信息。但是，如果您的服务可能涉及信用卡号等敏感信息，那么您可能出于明显的原因不想传递该信息。

希望有帮助。