エラー

この章では、Google API のエラーモデルの概要について説明します。また、エラーを適切に生成して処理する方法についての一般的なガイダンスもデベロッパーに提供します。

Google APIs では、プロトコルに依存しない単純なエラーモデルが使用されており、さまざまな API、各種の API プロトコル（gRPC や HTTP など）、異なるエラーコンテキスト（非同期、バッチ、ワークフローエラーなど）にわたって一貫したエクスペリエンスを提供できます。

エラーモデル

Google APIs のエラーモデルは、google.rpc.Status によって論理的に定義され、API エラーが発生すると、そのインスタンスがクライアントに返されます。次のコードスニペットは、エラーモデルの全体的な設計を示しています。

package google.rpc;

// The `Status` type defines a logical error model that is suitable for
// different programming environments, including REST APIs and RPC APIs.
message Status {
  // A simple error code that can be easily handled by the client. The
  // actual error code is defined by `google.rpc.Code`.
  int32 code = 1;

  // A developer-facing human-readable error message in English. It should
  // both explain the error and offer an actionable resolution to it.
  string message = 2;

  // Additional error information that the client code can use to handle
  // the error, such as retry info or a help link.
  repeated google.protobuf.Any details = 3;
}

ほとんどの Google API ではリソース指向の API 設計が採用されているため、エラー処理は、多数のリソースで一連の少数の標準エラーを使用することによって、同じ設計原則に従います。たとえば、さまざまな種類の「not found」エラーを定義する代わりに、サーバーは 1 つの標準 google.rpc.Code.NOT_FOUND エラーコードを使用して、特定のリソースが見つからないことをクライアントに伝えます。エラー空間が小さければ小さいほど、ドキュメントが単純化され、クライアントライブラリの独特なマッピングが改善され、クライアントロジックが単純化される一方で、実用価値のある情報の組み込みが制限されません。

エラーコード

Google API では、google.rpc.Code によって定義された正規のエラーコードを使用しなければなりません。デベロッパーが多数のエラーコードを処理するロジックを作成する可能性は非常に低いため、個々の API で追加のエラーコードを定義しないようにする必要があります。参考として、API 呼び出すごとに平均 3 つのエラーコードを処理する場合、ほとんどのアプリケーションロジックがエラー処理専用になり、デベロッパーエクスペリエンスが低下します。

エラーメッセージ

エラーメッセージは、ユーザーによる API エラーの理解と解決を簡単かつ迅速にするために役立つようにします。一般的に、エラーメッセージを作成する際は次のガイドラインを考慮してください。

ユーザーが API のエキスパートユーザーであると想定しないでください。ユーザーはクライアントデベロッパー、オペレーション担当者、IT スタッフ、アプリのエンドユーザーである場合があります。
ユーザーがサービスの実装について何でも知っている、またはエラーのコンテキスト（ログ分析など）を熟知していると想定しないでください。
可能な場合は、エラーメッセージはテクニカルユーザー（必ずしも API のデベロッパーではない）がエラーに対応して修正できるように作成してください。
エラーメッセージは簡潔にします。必要に応じて、ユーザーが困った場合に質問したり、フィードバックを送信したり、エラーメッセージに必ずしも含まれない情報にアクセスすることができるリンクを提供してください。それ以外の場合は、詳細フィールドを使用して拡張します。

エラーの詳細

Google API では、エラーの詳細に関する標準エラーペイロードのセットを定義しています。これは google/rpc/error_details.proto にあります。これらは、割り当ての失敗や無効なパラメータなど、API エラーの最も一般的なニーズに対応しています。エラーコードと同様、デベロッパーは可能な限りこうした標準ペイロードを使用してください。

追加のエラー詳細タイプは、アプリケーションコードによるエラー処理を支援できる場合にのみ導入してください。人間のみが処理できるエラー情報の場合は、追加のエラー詳細タイプを導入するのではなく、エラーメッセージの内容として情報を提供し、デベロッパーが手動で処理するようにします。

error_details ペイロードの例を次に示します。

ErrorInfo: 安定した、拡張可能な構造化エラー情報を提供します。
RetryInfo: 失敗したリクエストをクライアントがいつ再試行できるかを示します。Code.UNAVAILABLE または Code.ABORTED で返される場合があります。
QuotaFailure: 割り当てチェックがどのように失敗したかを示します。Code.RESOURCE_EXHAUSTED で返される場合があります。
BadRequest: クライアントリクエストの違反を示します。Code.INVALID_ARGUMENT で返される場合があります。

ErrorInfo

ErrorInfo は、特別な種類のエラーペイロードです。人間とアプリケーションの両方が利用できる、安定かつ拡張可能なエラー情報を提供します。それぞれの ErrorInfo には、エラーのドメイン、エラーの理由、一連のエラーのメタデータ（この例など）の、3 つの情報が含まれます。詳細については、ErrorInfo の定義をご覧ください。

Google API の場合、エラーのプライマリドメインは googleapis.com で、対応するエラーの理由は google.api.ErrorReason enum で定義されます。詳細については、google.api.ErrorReason の定義をご覧ください。

エラーのローカライズ

google.rpc.Status の message のフィールドはデベロッパー向けであり、英語でなければなりません。

ユーザー向けのエラーメッセージが必要な場合は、google.rpc.LocalizedMessage を詳細フィールドとして使用します。google.rpc.LocalizedMessage のメッセージフィールドはローカライズできますが、google.rpc.Status のメッセージフィールドが英語になっていることを確認してください。

デフォルトでは、API サービスは認証されたユーザーのロケールか、HTTP Accept-Language ヘッダーまたはリクエスト内の language_code パラメータを使用して、ローカライズの対象言語を判別します。

エラーのマッピング

Google APIs には、さまざまなプログラミング環境からアクセスできます。通常、各環境には、エラー処理の独自の方法があります。以降のセクションでは、広く使用されている環境でエラーモデルをマッピングする方法について説明します。

HTTP マッピング

proto3 メッセージには、ネイティブの JSON エンコードがありますが、Google の API プラットフォームでは、下位互換性を維持するため、Google の JSON HTTP APIs 用に別のエラースキーマを使用しています。

スキーマ:

// This message defines the error schema for Google's JSON HTTP APIs.
message Error {
  // Deprecated. This message is only used by error format v1.
  message ErrorProto {}
  // This message has the same semantics as `google.rpc.Status`. It uses HTTP
  // status code instead of gRPC status code. It has extra fields `status` and
  // `errors` for backward compatibility with [Google API Client
  // Libraries](https://developers.google.com/api-client-library).
  message Status {
    // The HTTP status code that corresponds to `google.rpc.Status.code`.
    int32 code = 1;
    // This corresponds to `google.rpc.Status.message`.
    string message = 2;
    // Deprecated. This field is only used by error format v1.
    repeated ErrorProto errors = 3;
    // This is the enum version for `google.rpc.Status.code`.
    google.rpc.Code status = 4;
    // This corresponds to `google.rpc.Status.details`.
    repeated google.protobuf.Any details = 5;
  }
  // The actual error payload. The nested message structure is for backward
  // compatibility with [Google API Client
  // Libraries](https://developers.google.com/api-client-library). It also
  // makes the error more readable to developers.
  Status error = 1;
}

例（リンク）:

{
  "error": {
    "code": 400,
    "message": "API key not valid. Please pass a valid API key.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "API_KEY_INVALID",
        "domain": "googleapis.com",
        "metadata": {
          "service": "translate.googleapis.com"
        }
      }
    ]
  }
}

gRPC マッピング

異なる RPC プロトコルは、エラーモデルを異なる方法でマッピングします。gRPC の場合、エラーモデルは、生成されたコードとサポートされている各言語のランタイムライブラリによってネイティブにサポートされます。詳細については、gRPC の API ドキュメントをご覧ください。例については、gRPC Java の io.grpc.Status をご覧ください。

クライアントライブラリマッピング

Google クライアントライブラリは、確立されたイディオムとの整合性を保つために、言語ごとに異なるエラーを表示することがあります。たとえば、google-cloud-go ライブラリでは google.rpc.Status と同じインターフェースを実装するエラーが返されますが、google-cloud-java では例外が発生します。

エラーの処理

次の表に、google.rpc.Code に定義されているすべての gRPC エラーコードと、その原因の簡単な説明を示します。エラーを処理するには、返されたステータスコードの説明を確認し、それに応じて呼び出しを変更します。

HTTP	gRPC	説明
200	`OK`	エラーはありません。
400	`INVALID_ARGUMENT`	クライアントが無効な引数を指定しました。詳しくは、エラーメッセージとエラーの詳細を確認してください。
400	`FAILED_PRECONDITION`	空でないディレクトリの削除など、現在のシステム状態ではリクエストを実行できません。
400	`OUT_OF_RANGE`	クライアントが無効な範囲を指定しました。
401	`UNAUTHENTICATED`	OAuth トークンがない、もしくは無効、期限切れのためにリクエストが認証されませんでした。
403	`PERMISSION_DENIED`	クライアントに十分な権限がありません。これは、OAuth トークンに正しいスコープが割り当てられていないか、クライアントに権限が付与されていない、または API が有効になっていないことが原因で発生します。
404	`NOT_FOUND`	指定されたリソースが見つかりません。
409	`ABORTED`	同時実行の競合（読み取り - 変更 - 書き込みの競合など）。
409	`ALREADY_EXISTS`	クライアントが作成しようとしたリソースはすでに存在します。
429	`RESOURCE_EXHAUSTED`	リソース割り当てが不足しているか、レート制限に達しています。詳しくは、クライアントは google.rpc.QuotaFailure エラーの詳細を確認してください。
499	`CANCELLED`	リクエストはクライアントによってキャンセルされました。
500	`DATA_LOSS`	復元できないデータ損失またはデータ破損。クライアントはエラーをユーザーに報告する必要があります。
500	`UNKNOWN`	不明なサーバーエラー。通常、サーバーのバグです。
500	`INTERNAL`	内部サーバーエラー。通常、サーバーのバグです。
501	`NOT_IMPLEMENTED`	API メソッドはサーバーによって実装されていません。
502	なし	サーバーに到達する前にネットワークエラーが発生しました。通常は、ネットワークの停止や構成ミスです。
503	`UNAVAILABLE`	サービス利用不可。通常、サーバーがダウンしています。
504	`DEADLINE_EXCEEDED`	リクエスト期限を超えました。これは、呼び出し元が、メソッドのデフォルト期限よりも短い期限を設定し（つまり、要求された期限はサーバーがリクエストを処理するのに十分ではない）、リクエストがその期限内に完了しなかった場合にのみ発生します。

エラー時の再試行

クライアントは、503 UNAVAILABLE エラーに対して、指数バックオフを使用して再試行することができます。最小遅延は、別途ドキュメント化されていない限り、1 秒にします。特に記載がない限り、デフォルトの再試行は 1 回にします。

429 RESOURCE_EXHAUSTED エラーの場合、クライアントは最小 30 秒の遅延で再試行できます。このような再試行は、長時間実行するバックグラウンドジョブに対してのみ有効です。

それ以外のすべてのエラーでは、再試行を行えない場合があります。まず、リクエストが冪等であることを確認してください。ガイダンスについては、google.rpc.RetryInfo をご覧ください。

エラーの伝搬

API サービスが他のサービスに依存している場合は、これらのサービスからエラーをそのままクライアントに伝播しないでください。エラーを翻訳するときには、次のことをおすすめします。

実装の詳細と機密情報を非表示にします。
エラーに関与する当事者を調整します。たとえば、別のサービスから INVALID_ARGUMENT エラーを受け取ったサーバーが、呼び出し元に INTERNAL を伝播するようにします。

エラーの再現

ログとモニタリングを分析してエラーを解決できない場合は、シンプルかつ繰り返し実行できるテストでエラーを再現してみてください。そのテストを使用することで、トラブルシューティング用に多くの情報を収集できます。また、テクニカルサポートに問い合わせる際にそれを提供できます。

curl -v とシステムパラメータを使用して、Google API のエラーを再現することをおすすめします。この組み合わせにより、ほぼすべての Google API リクエストを再現でき、詳細なデバッグ情報を提供できます。詳細については、呼び出す API のドキュメントをご覧ください。

エラーの生成

サーバー開発者は、クライアント開発者が問題を理解して解決するための十分な情報を含むエラーを生成するようにしてください。同時に、多くの場合、エラーは記録され、他のユーザーがアクセスできるため、ユーザーデータのセキュリティとプライバシーを考慮して、エラーメッセージとエラーの詳細で機密情報が開示されないようにする必要があります。たとえば、「Client IP address is not on allowlist 128.0.0.0/8」のようなエラーメッセージでは、サーバー側のポリシーに関する情報が公開されていますが、ログへのアクセス権を持つユーザーがアクセスできない可能性があります。

適切なエラーを生成するには、エラー状態ごとに最適なエラーコードを選択するため、まず google.rpc.Code を十分に理解する必要があります。サーバーアプリケーションは、複数のエラー状態を並行してチェックし、最初のエラー状態を返す場合があります。

次の表に、各エラーコードと適切なエラーメッセージの例を示します。

HTTP	gRPC	エラーメッセージの例
400	`INVALID_ARGUMENT`	リクエストフィールド x.y.z は xxx です。[yyy、zzz] のいずれかが必要です。
400	`FAILED_PRECONDITION`	リソース xxx は空でないディレクトリであるため、削除することはできません。
400	`OUT_OF_RANGE`	パラメータ「age」は [0、125] の範囲外です。
401	`UNAUTHENTICATED`	無効な認証情報。
403	`PERMISSION_DENIED`	許可「xxx」がリソース「yyy」に対して拒否されました。
404	`NOT_FOUND`	リソース「xxx」が見つかりません。
409	`ABORTED`	リソース「xxx」のロックを取得できませんでした。
409	`ALREADY_EXISTS`	リソース「xxx」はすでに存在します。
429	`RESOURCE_EXHAUSTED`	割り当て制限「xxx」を超えました。
499	`CANCELLED`	リクエストはクライアントによってキャンセルされました。
500	`DATA_LOSS`	注を参照。
500	`UNKNOWN`	注を参照。
500	`INTERNAL`	注を参照。
501	`NOT_IMPLEMENTED`	メソッド「xxx」は実装されていません。
503	`UNAVAILABLE`	注を参照。
504	`DEADLINE_EXCEEDED`	注を参照。

エラーのペイロード

google.rpc パッケージは、一連の標準エラーペイロードを定義します。これは、カスタムエラーペイロードよりも優先されます。次の表は、各エラーコードと一致する標準エラーペイロードを示しています（該当する場合）。高度なアプリケーションでは、エラーを処理する際、google.rpc.Status 内のエラーのペイロードを探すことをおすすめします。

HTTP	gRPC	推奨されるエラー詳細
400	`INVALID_ARGUMENT`	`google.rpc.BadRequest`
400	`FAILED_PRECONDITION`	`google.rpc.PreconditionFailure`
400	`OUT_OF_RANGE`	`google.rpc.BadRequest`
401	`UNAUTHENTICATED`	`google.rpc.ErrorInfo`
403	`PERMISSION_DENIED`	`google.rpc.ErrorInfo`
404	`NOT_FOUND`	`google.rpc.ResourceInfo`
409	`ABORTED`	`google.rpc.ErrorInfo`
409	`ALREADY_EXISTS`	`google.rpc.ResourceInfo`
429	`RESOURCE_EXHAUSTED`	`google.rpc.QuotaFailure`
499	`CANCELLED`
500	`DATA_LOSS`	`google.rpc.DebugInfo`
500	`UNKNOWN`	`google.rpc.DebugInfo`
500	`INTERNAL`	`google.rpc.DebugInfo`
501	`NOT_IMPLEMENTED`
503	`UNAVAILABLE`	`google.rpc.DebugInfo`
504	`DEADLINE_EXCEEDED`	`google.rpc.DebugInfo`

標準フィールド

命名規則