API的错误代码模式 [英] Error code pattern for API
问题描述
API错误代码响应模式的最佳选择是什么?
What are the good choice for API error code response pattern?
不是使用表示不同类型错误的不同代码
Instead of using different codes indicating different type of error
100001 // username not provided
100002 // password not provided
100003 // password too short
...
I see some other use patterns like the following (non-sequential) ...
20000
20001
20004
20015
还有其他建议吗?
推荐答案
在我开发和使用Web服务的经验中，我发现使用顶级HTTP状态代码和更低级API的组合的策略错误代码工作得很好.请注意，较低级别的API错误代码不必是整数，而可以是任何枚举.对于一个众所周知的公共示例，AWS简单电子邮件服务(SES)使用以下示例SES错误代码响应.请注意，尽管SES使用XML响应错误有效负载，但该策略对JSON响应有效负载同样有效.
In my experience developing and using web services, I have found that a strategy of using a combination of top-level HTTP status codes and lower level API error codes work reasonably well. Note that the lower level API error codes don't need to be integers, but can be any enumeration. For a well-known public example, AWS Simple Email Service (SES) uses this strategy of using both HTTP status codes and API level error codes. You can see a sample error code response for SES here. Note that although SES uses XML response error payloads, this strategy works equally well for JSON response payloads.
根据我的经验，使用此策略时需要牢记以下几点:
In my experience, there are a few things that you need to keep in mind when using this strategy:
- 力争返回正确的HTTP响应代码: HTTP是一个普遍存在的协议，毫无疑问您的Web容器可以理解.它的响应代码自然适合REST Web服务.因此，利用它吧！如果您的Web服务遇到错误情况，则应尽力返回正确的HTTP状态代码，在该上下文中，API错误代码具有含义.当开发人员无条件地将任意(通常是运行时)异常备份到堆栈中时，我在调试Web服务问题时最头疼的事情就发生了.结果是，即使不是这种情况，所有内容也都以HTTP 500(内部服务器错误)状态代码返回给调用方(例如，客户端发送垃圾数据，而服务器无法处理它.一些常见的HTTP状态代码)您可能要设计包括:
- 400错误的请求:客户的请求有问题.请注意，此错误不仅用于POST请求中的JSON语法损坏，而且它也是语义问题的合法响应代码(也就是JSON请求有效载荷符合规定的架构，但是有效载荷中的数据存在问题，例如当数字应该为正数时为负数).
- 401未经授权:呼叫者的凭据无效(即授权错误).
- 403禁止访问:呼叫者的凭据有效，但是其访问级别不足以访问资源(即身份验证错误).
- 404找不到: URL的资源不存在.
- 500内部服务器错误:服务器本身内部发生了一些错误，此错误可能是任何原因.
- 502错误的网关:调用下游服务时发生错误.
- 503服务不可用:一个有用的响应代码，当您遇到大量无意间使用DDOS服务的快乐"客户时，会感到不满意.
- 504网关超时:类似于502状态码，但是指示超时，而不是下游服务本身的实际错误.
- 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 Bad Request: There is an issue with the client's request. Note this error isn't just used for things like broken JSON syntax in a POST request, but it is also a legitimate response code for semantic issues as well (i.e. the JSON request payload conformed to the prescribed schema, but there was an issue with the data in the payload, such as a number being negative when it is supposed to be only positive).
- 401 Unauthorized: The caller's credentials were invalid (i.e. authorization error).
- 403 Forbidden: The caller's credentials were valid, but their access level isn't sufficient to access the resource (i.e. authentication error).
- 404 Not Found: The resource of the URL doesn't exist.
- 500 Internal Server Error: Something bad happened inside the server itself, this error could be anything.
- 502 Bad Gateway: An error occurred when calling downstream service.
- 503 Service Unavailable: A useful response code for when you get hammered with a ton of "happy" customers who are inadvertently DDOS'ing your service.
- 504 Gateway Timeout: Like the 502 status code, but indicates a timeout instead of an actual error with the downstream service, per se.
希望有帮助.
这篇关于API的错误代码模式的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
