APIのエラーコードパターン

APIエラーコードの応答パターンに適したものは何ですか?

異なる種類のエラーを示す異なるコードを使用する代わりに

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

が表示される次のような他の使用パターン(非連続)...

20000
20001
20004
20015

他に推奨事項はありますか?

5
あなたのユースケースは何ですか?
追加された 著者 entpnerd,

5 答え

IETF(インターネット標準化団体)による推奨はapplication/problem + jsonメディアタイプの使用です。

注目に値するのは、彼らは乱数を使わず、エラーを識別するために文字列(特にuris)を使うことです。

これは主観的な質問ですが、その形式を使用しなくても、 username-not-provided100001 よりも優れていると私は主張します。

5
追加された

私がWebサービスを開発し使用してきた経験では、トップレベルのHTTPステータスコードと下位レベルのAPIエラーコードの組み合わせを使用する方法が妥当に機能することを確認しました。下位レベルのAPIエラーコードは整数である必要はありませんが、任意の列挙型にすることができます。よく知られた一般的な例では、AWS Simple Email Service(SES)はこれを使用します。 HTTPステータスコードとAPIレベルのエラーコードの両方を使用する戦略。 SESのサンプルエラーコードの応答がここに表示されます/ a>。 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 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).
  2. 401 Unauthorized: The caller's credentials were invalid (i.e. authorization error).
  3. 403 Forbidden: The caller's credentials were valid, but their access level isn't sufficient to access the resource (i.e. authentication error).
  4. 404 Not Found: The resource of the URL doesn't exist.
  5. 500 Internal Server Error: Something bad happened inside the server itself, this error could be anything.
  6. 502 Bad Gateway: An error occurred when calling downstream service.
  7. 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.
  8. 504 Gateway Timeout: Like the 502 status code, but indicates a timeout instead of an actual error with the downstream service, per se.
  9. HTTP response codes are the top-level codes, and API error codes only have meaning within that context: By this, I mean that your API error codes are only meaningful for certain HTTP response codes. For example, in the
  10. table of SES error codes, each error code is only tied to a single HTTP(S) response code. The error codes ConfigurationSetDoesNotExistand InvalidParameterValueonly make sense when a 400 Bad Requestis returned by SES - it wouldn't make sense to return these status codes when a 500 Internal Server Erroris returned. Similarly, if you were writing a web service that called downstream services and databases, you might have a FooDownstreamServiceTimedOuterror code that you would return with a 504 Gateway TimeoutHTTP status code when a downstream web service call timed out to the "Foo" web service. You might also have a MyDatabaseErrorerror code that you would return with a 500 Internal Server ErrorHTTP status code when your query to the internal DB fails.
  11. Have a uniform error code schema irrespective of status codes: Your clients need to be able to process your error content programmatically. As such, it needs to conform to a certain schema. Ideally, your API error code schema should include the error code (i.e. name or ID, etc.). You also probably want to include a natural language description of the error code and the ID/GUID of the request that you are responding to. For an example of an error schema, see
  12. this sample AWS SES response and schema. Additionally, you might also want to consider returning a client ID in the response. This is as much for your own benefit as the client's since it can help you drill down into the data to see if one particular client is getting a glut of particular errors vs. your other clients.
  13. Consider returning natural language descriptions of the error codes in the response: To make things easier on your clients, you might want to consider not just returning the error code in the error payload, but a natural language description as well. This kind of behavior can immediately help confused and busy engineers who really don't care that much about your service quickly diagnose what's happening so that they can resolve the issue ASAP. btw, enabling engineers to quickly diagnose issues with your service increases the all-important "uptime" metric that your customers and managers will no doubt care about.
  14. Don't feel obliged to use integers, use enumerations instead: The notion of "error codes" conjures up images of outdated technologies and codebooks where you had to look up what an error meant. It arose from the programming dark ages when engineers needed to fit all possible errors into a byte of space, or a nibble or whatever. Those days are gone, and your error code can be a string, likely without any meaningful impact on performance. You might as well take advantage and make the error code meaningful, as a means of keeping things simple.
  15. Return info to clients that they might need to debug, but be mindful of security: If possible, return whatever debug info your clients may need. However, if your service potentially deals with sensitive information such as credit card numbers and the like, you probably don't want to pass that info around for obvious reasons.

それが役立つことを願っています。

4
追加された

最初から独自のAPI標準を作成する代わりに、すでに使用可能な標準の1つを採用します。例えば、 JSON API 標準のようになります。

JSONレスポンスのフォーマット方法についてチームと議論したことがある場合は、JSON APIを使用して、自転車に乗らないようにすることができます。

     

共通の規約に従うことで、生産性を向上させ、一般的なツールを活用し、重要なことに焦点を合わせることができます。アプリケーション。

     

JSON APIを中心に構築されたクライアントは、レスポンスを効率的にキャッシュする機能を利用して、ネットワークリクエストを完全に排除することができます。

JSON APIを使用する場合は、エラー専用セクションいくつかのエラー例

0
追加された

何年もの間、多くの開発会社がエラー用のビットマスクのようなものを作成してきたので、エラーの中に複数の変数をエンコードすることができます。

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の可能な組み合わせのように、それはあなたにとって十分かもしれませんし、そうでないかもしれません。

You see this being common in COM+ https://docs.microsoft.com/en-us/windows/desktop/com/com-error-codes-1

これが役に立つことを願っています。

0
追加された

私はこれがあなたがどんな種類のAPIを提供しているかに強く依存すると言うでしょう。

ack または failurewarningsuccess <�という3つの状態を持つすべての応答に、常に ack というフィールドを含めるようにしました。/code>。成功は明らかにすべてがうまくいったということです。警告が発生すると、リクエストは処理され、JSONには予想される出力が含まれますが、 warning 文字列も含まれます。複数の警告が発生した場合は errors </<code> codestring 、および type を含む複数のオブジェクトで構成されます。この配列は failure の場合にも返されますが、この配列以外は何もしません。

この配列には、エラーまたは警告ごとに1つのオブジェクトが含まれ、コード(最初の10001、10002などを使用することをお勧めします)と非常に短いフレーズでエラーを説明する文字列( Username contains invalidが含まれます)文字)。 type は、 error または warning のいずれかです。これは、エラーだけでなく failure ackの場合に役立ちます。しかしまた警告。

これにより、エラーをそれらのコードで簡単に探すことができます(私はまた、APIの長いページに、それらの短くて長い説明と一般的な原因/修正などを含むページを提供します)。情報はエラーコードを提供することでアクセスできるAPI経由でも利用可能であるべきであり、それでもユーザーはエラーを調べる必要なしにほとんどの場合に何が悪いのかを伝えることができます。

これにより、開発者だけでなく、エンドユーザーへの警告やエラーの簡単な出力も可能になります。私の考えをAPI呼び出しと共に使用してエラーに関する情報を取得すると、APIを使用している開発者は、必要に応じてエラーに関する完全な情報をエンドユーザーに簡単に提供できます(原因/修正など)

0
追加された
JavaScript - 日本のコミュニティ
JavaScript - 日本のコミュニティ
2 参加者の

日本人コミュニティのjavascript