Package google.rpc

インデックス

BadRequest

クライアント リクエストの違反について説明します。このエラータイプは、リクエストの構文的な側面に焦点を当てています。

フィールド
field_violations[]

FieldViolation

クライアント リクエストのすべての違反について説明します。

FieldViolation

単一の無効なリクエスト フィールドを説明するために使用されるメッセージ タイプ。

フィールド
field

string

リクエスト本文のフィールドへのパス。値は、プロトコル バッファ フィールドを識別する、ドットで区切られた識別子のシーケンスになります。

次の点を考慮してください。

message CreateContactRequest {
  message EmailAddress {
    enum Type {
      TYPE_UNSPECIFIED = 0;
      HOME = 1;
      WORK = 2;
    }

    optional string email = 1;
    repeated EmailType type = 2;
  }

  string full_name = 1;
  repeated EmailAddress email_addresses = 2;
}

この例では、proto field は次のいずれかの値をとります。

  • full_name 値の違反に対する full_name
  • 最初の email_addresses メッセージの email フィールドの違反に対する email_addresses[1].email
  • 3 番目の email_addresses メッセージの 2 番目の type 値の違反に対する email_addresses[3].type[2]。

JSON では、同じ値は次のように表されます。

  • fullName 値の違反に対する fullName
  • 最初の emailAddresses メッセージの email フィールドの違反に対する emailAddresses[1].email
  • 3 番目の emailAddresses メッセージの 2 番目の type 値の違反に対する emailAddresses[3].type[2]。
description

string

リクエスト要素が不適切な理由の説明。
reason

string

フィールドレベルのエラーの理由。これは、フィールドレベルのエラーの直接の原因を特定する定数値です。google.rpc.ErrorInfo.domain のスコープ内で FieldViolation のタイプを一意に識別する必要があります。これは 63 文字以下で、UPPER_SNAKE_CASE を表す正規表現 [A-Z][A-Z0-9_]+[A-Z0-9] に一致する必要があります。
localized_message

LocalizedMessage

API コンシューマーに安全に返せる、フィールドレベルのエラーのローカライズされたエラー メッセージを提供します。

コード

gRPC API の正規のエラーコード。

複数のエラーコードが該当する場合があります。サービスは、該当する最も具体的なエラーコードを返す必要があります。たとえば、両方のコードが該当する場合、FAILED_PRECONDITION より OUT_OF_RANGE を優先します。同様に、FAILED_PRECONDITION より NOT_FOUND または ALREADY_EXISTS を優先します。

列挙型
OK

エラーではありません。成功したときに返されます。

HTTP マッピング: 200 OK
CANCELLED

オペレーションがキャンセルされました。通常、キャンセルは呼び出し元により行われます。

HTTP マッピング: 499 クライアントのクローズ リクエスト
UNKNOWN

不明なエラーです。たとえば、別のアドレス空間から受信した Status 値がこのアドレス空間で不明なエラー空間に属している場合に、このエラーが返される可能性があります。また、十分なエラー情報を返さない API によって発生したエラーは、このエラーに変換できます。

HTTP マッピング: 500 内部サーバーエラー
INVALID_ARGUMENT

クライアントが無効な引数を指定しました。これは FAILED_PRECONDITION とは異なることに注意してください。INVALID_ARGUMENT は、システムの状態を問わず問題（ファイル名の形式が不適切であるなど）があった引数を示します。

HTTP マッピング: 400 不正なリクエスト
DEADLINE_EXCEEDED

オペレーションが完了する前に期限が切れました。システムの状態を変更するオペレーションの場合、オペレーションが正常に終了しても、このエラーが返されることがあります。たとえば、サーバーからの正常なレスポンスが期限切れになるほど遅延する場合もあります。

HTTP マッピング: 504 ゲートウェイ タイムアウト
NOT_FOUND

一部のリクエストされたエンティティ（ファイルやディレクトリなど）が見つかりませんでした。

サーバー デベロッパーへの注: 段階的な機能のロールアウトや文書化されていない許可リストなど、ユーザークラス全体に対してリクエストが拒否された場合は、NOT_FOUND を使用できます。ユーザー単位のアクセス制御など、あるユーザークラス内の一部のユーザーに対してリクエストが拒否された場合は、PERMISSION_DENIED を使用する必要があります。

HTTP マッピング: 404 見つかりません
ALREADY_EXISTS

クライアントが作成しようとしたエンティティ（ファイルまたはディレクトリなど）はすでに存在しています。

HTTP マッピング: 409 競合
PERMISSION_DENIED

呼び出し元には、指定されたオペレーションを実行する権限がありません。PERMISSION_DENIED は一部のリソースが枯渇し拒否されたため使用できません（このようなエラーには代わりに RESOURCE_EXHAUSTED を使用します）。呼び出し元が特定できない場合は、PERMISSION_DENIED を使用しないでください（このようなエラーには代わりに UNAUTHENTICATED を使用します）。このエラーコードは、リクエストが有効であること、リクエストされたエンティティが存在すること、および他の事前条件が満たされていることを意味するものではありません。

HTTP マッピング: 403 禁止です
UNAUTHENTICATED

リクエストにはオペレーションに有効な認証情報がありません。

HTTP マッピング: 401 権限なし
RESOURCE_EXHAUSTED

ユーザーごとの割り当て、またはファイル システム全体で容量が不足しているため、一部のリソースが枯渇しています。

HTTP マッピング: 429 リクエストが多すぎます
FAILED_PRECONDITION

システムがオペレーションの実行に必要な状態ではないため、オペレーションが拒否されました。たとえば、削除されるディレクトリが空でない、rmdir オペレーションがディレクトリ以外に適用されているなどの状態です。

サービスの実装者は、次のガイドラインを使用して、FAILED_PRECONDITION、ABORTED、UNAVAILABLE のいずれかに決定できます。（a）クライアントが失敗した呼び出しのみを再試行できる場合は、UNAVAILABLE を使用します。（b）クライアントがより高いレベルで再試行する必要がある場合は、ABORTED を使用します。たとえば、クライアント指定のテストと設定が失敗し、クライアントが読み取り、変更、書き込みのシーケンスをやり直す必要がある場合です。（c）システムの状態が明示的に修正されるまでクライアントが再試行すべきでない場合は、FAILED_PRECONDITION を使用します。たとえば、ディレクトリが空でないため「rmdir」が失敗した場合は、ディレクトリからファイルが削除されない限りクライアントは再試行すべきではないため、FAILED_PRECONDITION を返します。

HTTP マッピング: 400 不正なリクエスト
ABORTED

オペレーションは、通常、シーケンサー チェックの失敗、またはトランザクションの中止などの同時実行の問題のために中止されています。

FAILED_PRECONDITION、ABORTED、UNAVAILABLE の決定については、上記のガイドラインをご覧ください。

HTTP マッピング: 409 競合
OUT_OF_RANGE

オペレーションが有効な範囲を超えて試行されました。たとえば、ファイルの終わりを超えたシークまたは読み取りなどが該当します。

INVALID_ARGUMENT とは異なり、このエラーは、システムの状態が変化すれば修正できる可能性のある問題を示しています。たとえば、32 ビット ファイルシステムは [0,2^32-1] の範囲にないオフセットでの読み取りを要求されると、INVALID_ARGUMENT を生成しますが、現在のファイルサイズを超えるオフセットからの読み取りを要求されると、OUT_OF_RANGE を生成します。

FAILED_PRECONDITION と OUT_OF_RANGE は重複しています。空間を経由して反復している呼び出し元が、完了時に OUT_OF_RANGE エラーを簡単に探せるようにするために、可能な限り OUT_OF_RANGE（より具体的なエラー）の使用をおすすめします。

HTTP マッピング: 400 不正なリクエスト
UNIMPLEMENTED

オペレーションが実装されていないか、このサービスでサポートまたは有効にされていません。

HTTP マッピング: 501 実装されていません
INTERNAL

内部エラー。これは、基盤となるシステムで予期される一部の不変条件が満たされていないことを意味します。このエラーコードは深刻なエラーのために予約されています。

HTTP マッピング: 500 内部サーバーエラー
UNAVAILABLE

サービスは現在使用できません。これは、バックオフで再試行することで解決できる可能性が高い一時的な状態です。非べき等オペレーションの再試行が常に安全であるとは限りません。

FAILED_PRECONDITION、ABORTED、UNAVAILABLE の決定については、上記のガイドラインをご覧ください。

HTTP マッピング: 503 サービスを利用できません
DATA_LOSS

回復不能なデータの消失や破損。

HTTP マッピング: 500 内部サーバーエラー

ErrorInfo

エラーの原因を構造化された詳細で説明します。

「pubsub.googleapis.com」API が有効になっていない場合に、この API にアクセスすると、次のようなエラーが発生します。

{ "reason": "API_DISABLED"
  "domain": "googleapis.com"
  "metadata": {
    "resource": "projects/123",
    "service": "pubsub.googleapis.com"
  }
}

このレスポンスは、pubsub.googleapis.com API が有効になっていないことを示しています。

在庫切れのリージョンで Spanner インスタンスを作成しようとしたときに返されるエラーの例:

{ "reason": "STOCKOUT"
  "domain": "spanner.googleapis.com",
  "metadata": {
    "availableRegions": "us-central1,us-east2"
  }
}
フィールド
reason

string

エラーの理由。これは、エラーの直接の原因を特定する定数値です。エラーの理由は、特定のエラー ドメイン内で一意です。これは 63 文字以下で、UPPER_SNAKE_CASE を表す正規表現 [A-Z][A-Z0-9_]+[A-Z0-9] に一致する必要があります。
domain

string

「理由」が属する論理グループ。通常、エラー ドメインはエラーを生成したツールまたはプロダクトの登録済みサービス名です。例: 「pubsub.googleapis.com」。エラーが共通のインフラストラクチャによって生成された場合、エラー ドメインはインフラストラクチャを識別するグローバルに一意の値である必要があります。Google API インフラストラクチャの場合、エラー ドメインは「googleapis.com」です。
metadata

map<string, string>

このエラーに関する構造化された追加の詳細。

キーは [a-z][a-zA-Z0-9-_]+ の正規表現と一致する必要がありますが、理想的には lowerCamelCase にします。また、長さは 64 文字に制限する必要があります。上限を超えた現在の値を特定する場合、単位は値ではなくキーに含める必要があります。たとえば、クライアントが 1 回のリクエスト（バッチ）で作成できるインスタンスの数を超えた場合、{"instanceLimit": "100/request"} ではなく {"instanceLimitPerRequest": "100"} が返される必要があります。

ヘルプ

ドキュメントへのリンクまたは帯域外アクションを実行するためのリンクを提供します。

たとえば、呼び出し元プロジェクトがアクセスされたサービスを有効にしていないことを示すエラーで割り当てチェックが失敗した場合、これには、デベロッパー コンソールの適切な場所に直接移動してビットを反転させるための URL が含まれることがあります。

フィールド

LocalizedMessage

RPC エラーに付加できる、ユーザーに返しても安全なローカライズされたエラー メッセージを提供します。

フィールド
locale

string

https://www.rfc-editor.org/rfc/bcp/bcp47.txt で定義されている仕様に沿って使用されるロケール。例: 「en-US」、「fr-CH」、「es-MX」
message

string

上記の言語 / 地域でのローカライズされたエラー メッセージ。

PreconditionFailure

失敗した前提条件について説明します。

たとえば、利用規約の承認が必要であるために RPC が失敗した場合、PreconditionFailure メッセージに利用規約違反が一覧表示される可能性があります。

フィールド
violations[]

Violation

すべての前提条件違反について説明します。

違反

単一の前提条件の失敗を説明するために使用されるメッセージ タイプ。

フィールド
type

string

PreconditionFailure のタイプ。サービス固有の列挙型を使用して、サポートされている前提条件違反のサブジェクトを定義することをおすすめします。たとえば、「利用規約違反」の場合は「TOS」となります。
subject

string

失敗したタイプに関連するサブジェクト。たとえば、「TOS」タイプに関する「google.com/cloud」では、どの利用規約を参照しているかが示されます。
description

string

前提条件が失敗した理由の説明。デベロッパーはこの説明を使用して、失敗の修正方法を理解できます。

例: 承認されなかった利用規約。

QuotaFailure

割り当てチェックがどのように失敗したかを説明します。

たとえば、呼び出し元プロジェクトで 1 日の上限を超えた場合、サービスは、プロジェクト ID と超過した割り当て上限の説明を含む QuotaFailure の詳細を返します。呼び出し元プロジェクトでデベロッパー コンソールでサービスが有効になっていない場合、サービスはプロジェクト ID を返して service_disabled を true に設定できます。

割り当ての失敗の処理に関するその他の詳細については、RetryInfo 型と Help 型もご覧ください。

フィールド
violations[]

Violation

すべての割り当て違反について説明します。

違反

単一の割り当て違反を説明するために使用されるメッセージ タイプ。たとえば、1 日の割り当て量やカスタム割り当て量を超えた場合などです。

フィールド
subject

string

割り当てチェックが失敗したサブジェクト。たとえば、「clientip:」や「project:」などです。
description

string

割り当てチェックがどのように失敗したかの説明。クライアントはこの説明を使用して、サービスの一般公開ドキュメントで割り当て構成の詳細を確認したり、デベロッパー コンソールで関連する割り当て上限を見つけて調整したりできます。

例: 「サービスが無効」または「読み取りオペレーションの 1 日の上限を超えました」。
api_service

string

QuotaFailure.Violation の送信元となる API サービス。割り当ての問題は、呼び出された API サービス以外の API サービスから発生することがあります。つまり、呼び出された API サービスの依存関係が QuotaFailure の原因である可能性があり、このフィールドには依存関係 API サービス名が設定されます。

たとえば、呼び出された API が Kubernetes Engine API（container.googleapis.com）で、Kubernetes Engine API 自体で割り当て違反が発生した場合、このフィールドは「container.googleapis.com」になります。一方、Kubernetes Engine API が Compute Engine API（compute.googleapis.com）で VM を作成するときに割り当て違反が発生した場合、このフィールドは「compute.googleapis.com」になります。
quota_metric

string

違反した割り当ての指標。割り当て指標は、API リクエストや CPU などの使用量を測定する名前付きカウンタです。サービスでアクティビティ（仮想マシンの割り当てなど）が発生すると、1 つ以上の割り当て指標が影響を受ける可能性があります。

例: 「compute.googleapis.com/cpus_per_vm_family」、「storage.googleapis.com/internet_egress_bandwidth」。
quota_id

string

違反した割り当ての ID。「上限名」とも呼ばれます。API サービスのコンテキストにおける割り当ての一意の識別子です。

たとえば、「CPUS-PER-VM-FAMILY-per-project-region」などです。
quota_dimensions

map<string, string>

違反した割り当てのディメンション。グローバル以外の割り当ては、一連のディメンションに適用されます。割り当て指標はカウント対象を定義しますが、ディメンションはカウンタを増やす対象の側面を指定します。

たとえば、「リージョンあたりの VM ファミリーあたりの CPU」割り当ては、「リージョン」と「vm_family」のディメンションで「compute.googleapis.com/cpus_per_vm_family」指標に上限を適用します。違反がリージョン「us-central1」で VM ファミリー「n1」に対して発生した場合、quota_dimensions は次のようになります。

{ "region": "us-central1", "vm_family": "n1", }

割り当てがグローバルに適用される場合、quota_dimensions は常に空になります。
quota_value

int64

QuotaFailure の時点での適用済み割り当て値。

たとえば、CPU 数に対する QuotaFailure の時点での適用済み割り当て値が「10」の場合、このフィールドの値にはこの数量が反映されます。
future_quota_value

int64

違反時にロールアウトされる新しい割り当て値。ロールアウトが完了すると、この値が quota_value の代わりに適用されます。違反時にロールアウトが進行中の場合、このフィールドは設定されません。

たとえば、違反時にロールアウトが進行中で、CPU 数の割り当てが 10 から 20 に変更されている場合、このフィールドの値は 20 になります。

RequestInfo

クライアントがバグを報告したり、他の形式のフィードバックを提供したりする際に添付できるリクエストに関するメタデータが含まれます。

フィールド
request_id

string

生成したサービスによってのみ解釈される不透明な文字列。たとえば、サービスログ内のリクエストを識別するために使用できます。
serving_data

string

このリクエストの処理に使用されたデータ。たとえば、デバッグのためにサービス プロバイダに送り返すことができる暗号化されたスタック トレースなどです。

ResourceInfo

アクセスされているリソースを説明します。

フィールド
resource_type

string

アクセスされるリソースのタイプの名前（「sql table」、「cloud storage bucket」、「file」、「Google calendar」など）、またはリソースのタイプ URL（「type.googleapis.com/google.pubsub.v1.Topic」など）。
resource_name

string

アクセスされているリソースの名前。たとえば、現在のエラーが google.rpc.Code.PERMISSION_DENIED の場合、共有カレンダーの名前は「example.com_4fghdhgsrgh@group.calendar.google.com」です。
owner

string

リソースのオーナー（省略可）。たとえば、「user:」や「project:」などです。
description

string

このリソースにアクセスしたときに発生したエラーについて説明します。たとえば、クラウド プロジェクトを更新するには、デベロッパー コンソール プロジェクトに対する writer 権限が必要になることがあります。

RetryInfo

クライアントが失敗したリクエストをいつ再試行できるかを示します。クライアントは、エラー レスポンスにこの情報がない場合、ここで推奨事項を無視するか、再試行できます。

再試行する際は、常に指数バックオフを使用することをおすすめします。

クライアントは、エラー レスポンスを受信してから retry_delay 時間が経過するまで待機してから再試行する必要があります。リクエストの再試行も失敗した場合は、クライアントは指数バックオフ スキームを使用して、retry_delay に基づいて再試行間の遅延を徐々に増やします。再試行の最大回数に達するか、再試行の最大遅延上限に達するまで続けます。

フィールド
retry_delay

Duration

クライアントは、同じリクエストを再試行するまでに少なくともこの時間待機する必要があります。

ステータス

Status 型は、REST API や RPC API など、さまざまなプログラミング環境に適した論理エラーモデルを定義します。gRPC により使用されます。各 Status メッセージには、エラーコード、エラー メッセージ、エラーの詳細という 3 種類のデータが含まれます。

このエラーモデルと操作方法について詳しくは、API 設計ガイドをご覧ください。

フィールド
code

int32

ステータス コード。google.rpc.Code の列挙値である必要があります。
message

string

デベロッパー向けのエラー メッセージ。英語で記述します。ユーザー向けのエラー メッセージは、ローカライズして google.rpc.Status.details フィールドで送信するか、クライアントでローカライズする必要があります。
details[]

Any

エラーの詳細を保持するメッセージのリスト。API が使用する共通のメッセージ タイプのセットがあります。