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

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

RequestInfo

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

フィールド
request_id

string

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

string

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

ステータス

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

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

フィールド
code

int32

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

string

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

Any

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