このページでは、BigQuery API から返される HTTP ステータス コードとエラー メッセージについて説明します。これらのコードを使用して、リクエスト エラーのトラブルシューティングと解決、API の動作の確認を行うことができます。
API 以外のエラー、クライアント ライブラリの接続エラー、 Google Cloud コンソール エラーの詳細については、エラー メッセージをご覧ください。
クエリエラーの詳細については、クエリに関する問題のトラブルシューティングをご覧ください。
ストリーミング挿入エラーの詳細については、ストリーミング挿入のトラブルシューティングをご覧ください。
エラー レスポンスの形式
BigQuery は、API に標準の HTTP エラー レポート形式を使用します。リクエストが成功すると、2xx の範囲の HTTP ステータス コードが返されます。失敗したリクエストは、4xx と 5xx の範囲のステータス コードを返します。リダイレクトが必要なリクエストは、3xx 範囲のステータス コードを返します。エラー レスポンスの本文には通常、JSON ドキュメントが含まれます。このドキュメントには、エラーに関する情報を含むエラー オブジェクトが含まれています。
BigQuery API レスポンスでは、エラー オブジェクトは通常、次のいずれかになります。
errorsオブジェクト。これには、ErrorProtoオブジェクトの配列が含まれます。errorResultsオブジェクト。これには、単一のErrorProtoオブジェクトが含まれます。
このページのステータス コード表の「理由」列は、ErrorProto オブジェクトの reason プロパティに対応しています。bq コマンドライン ツールを使用してジョブ ステータスを確認する場合は、--format=prettyjson フラグ(bq --format=prettyjson show -j <var>JOB_ID</var> など)または --apilog=stdout を使用して、エラー オブジェクトとその reason プロパティを表示します。
次の表に、エラーのレスポンス本文に表示される要素を示します。フィールドを組み合わせて使用することで、問題の特定に役立ちます。また、次の表のサンプル値は説明用であり、使用可能なすべての値の完全なリストではありません。
| 要素 | 説明 |
|---|---|
code |
HTTP ステータス コードの値。テキストによる説明は含まれません。 値の例としては、 400(Bad Request)、403(Forbidden)、404(Not Found)などがあります。 |
error |
エラー情報のコンテナ。 |
errors |
エラーの詳細を含むコンテナ。 |
エラー。domain |
エラーの範囲。値の例としては、global、usageLimits などがあります。 |
エラー。location |
エラーの原因となった locationType 内の特定のアイテム。たとえば、パラメータに無効な値を指定した場合、location はパラメータの名前になります。値の例としては、 Authorization や project などがあります。 |
エラー。locationType |
エラーの原因となったリクエストの場所または部分。location と組み合わせて使用すると、エラーを特定できます。値の例としては、 header や parameter などがあります。 |
エラー。message |
エラーの説明。 値の例としては、 Invalid argument、Access Denied、Not Found: Dataset myproject:foo などがあります。 |
エラー。reason |
エラーの原因の固有識別子。 値の例としては、 invalid、accessDenied、notFound などがあります。 |
message |
エラーの説明。errors.message と同じです。 |
HTTP ステータス コードとエラーコード
このセクションでは、BigQuery API の HTTP ステータス コードとエラーコードの一部を示します。1xx 情報コードと 2xx 成功コードは省略されています。詳細については、RFC 7231 §6、RFC 7232 §4、RFC 7233 §4、RFC 7235 §3、RFC 6585 のレスポンス ステータス コードをご覧ください。
400 - 不正なリクエスト
| 理由 | HTTP ステータス コード | 説明 | トラブルシューティング |
|---|---|---|---|
badRequest |
400 |
DML ステートメントは、以前の |
BigQuery Storage Write API(gRPC)に移行し、ストリーミング バッファがフラッシュされるまで数分待つか、ステートメントをフィルタして最近ストリーミングされた行を除外します。詳細については、ストリーミング バッファを含むテーブルに対する DML ステートメントをご覧ください。 |
invalid |
400 |
リクエストに、無効なクエリ以外の無効な入力が含まれています。たとえば、次のような場合です。
|
指定されたスキーマが既存の列とモードに一致していることを確認し、15 レベルを超えるネスト構造をフラット化(または |
invalidQuery |
400 |
SQL クエリの検証または実行チェックが失敗する理由は次のいずれかです。
|
|
jobBackendError |
400 |
|
切り捨て型指数バックオフを使用して、新しい |
jobInternalError |
400 |
|
切り捨て型指数バックオフを使用して、新しい |
preconditionFailed |
400 |
リクエストの前提条件が満たされていません。たとえば、次のような場合です。
|
再試行する前に現在のリソース |
resourceInUse |
400 |
削除リクエストの対象が、まだアクティブなリソースまたはデータが入力されているリソースである。
エラーが返されます: |
データセットを削除する前に空にするか(または |
resourcesExceeded |
400 |
ジョブが次のいずれかの領域で実行リソースの上限を超えている。
エラーが返されます: |
クエリを簡素化する、DML オペレーションをバッチ処理する、スキャンされる列またはパーティションを減らす、同じセッションで同時実行ジョブを回避する、シャッフルが多いワークロードに専用のスロット容量をプロビジョニングする。サブタイプごとの手順については、リソース超過に関する問題のトラブルシューティングとクエリがメモリリソースを超過するをご覧ください。 |
storageUnusable |
400 |
サービス側のストレージの問題により、テーブルのデータを保持する内部 BigQuery ストレージが一時的に使用できなくなっています。エラーは次のとおりです。
|
切り捨て型指数バックオフを使用してジョブを再試行します。詳細については、テーブル ストレージが使用できないをご覧ください。 |
streamingDataUnavailable |
400 |
書き込みが最適化されたストレージに最近ストリーミングされたデータは、読み取りジョブで一時的に使用できなくなります。エラーは |
切り捨て型指数バックオフを使用して、新しい |
tableUnavailable |
400 |
BigQuery は、次のようなデータが管理されていないテーブルを読み取ることができません。
|
指数バックオフ(切り捨て)を使用して、スキーマの取得またはバッキング テーブルのタイムアウトを再試行します。または、 |
userOwnedResourceError |
400 |
所有している外部リソースに BigQuery からアクセスすると、エラーが返されます。エラーが返されます: |
エラー メッセージの resource_type と resource_name を調べて外部リソースを特定し、external_error で報告された根本的なエラーを解決します。詳細については、ユーザー所有の外部リソースエラーをご覧ください。 |
vortexDataUnavailable |
400 |
BigQuery Storage Write API(gRPC)を使用して書き込み最適化ストレージに最近ストリーミングされたデータは、クエリで一時的に使用できません。エラーは |
切り捨て型指数バックオフを使用して、新しい |
billingTierLimitExceeded |
400 |
オンデマンド クエリが、スキャンされたデータあたりの最大 CPU 使用量の上限を超えている。エラーは |
SQL をリファクタリングして、意図しないデカルト積、不正確な結合、パーティション分割されていないウィンドウ関数、重い JavaScript UDF を削除するか、容量ベース(スロット)の料金に切り替えます。詳細については、クエリが CPU リソースを超過すると SQL アンチパターンを回避するをご覧ください。 |
bytesBilledLimitExceeded |
400 |
クエリの実行前のバイト数の上限の見積もりが、実行開始前に |
ドライランで推定バイト数をプレビューし、必要な列のみを選択して、パーティション分割された列をフィルタしてデータ処理を削減するか、 |
jobRateLimitExceeded |
400 |
|
同時送信を減らし(または、継続的クエリにバッチ優先度またはスロットの自動スケーリングを使用し)、切り捨て指数バックオフを使用して新しい |
timeout |
400 |
オペレーションが実行時間の上限を超えている。たとえば、次のような場合です。
|
パーティション分割された列またはクラスタ化された列をフィルタリングし、複雑なクエリまたはマルチステートメント クエリを小さなステージに分割します。または、外部テーブルを作成するときに、明示的なスキーマとより狭いソース URI を指定します。詳細については、クエリが実行時間の上限を超えていると割り当てと上限のエラーのトラブルシューティングをご覧ください。 |
invalidUser |
400 |
スケジュールされたクエリが無効なユーザー認証情報で構成されている。 |
スケジュールされたクエリのユーザー認証情報を更新します。詳細については、クエリのスケジュール設定をご覧ください。 |
required |
400 |
実行前に必要な入力がありません。
エラーが返されます: |
BigQuery API リファレンスまたはクライアント ライブラリのドキュメントで、必要なリクエスト本文とクエリ パラメータを確認し、API を呼び出す前に構成オブジェクトを検査します。詳細については、必要なパラメータがありませんをご覧ください。 |
401 - Unauthorized
リクエストに有効な認証情報がない場合に返されるエラー レスポンスの例を次に示します。
401 Unauthorized
{
"error": {
"errors": [
{
"domain": "global",
"reason": "unauthenticated",
"message": "Request had invalid authentication credentials. Expected OAuth 2 access token, login cookie or other valid authentication credential."
}
],
"code": 401,
"message": "Request had invalid authentication credentials. Expected OAuth 2 access token, login cookie or other valid authentication credential.",
"status": "UNAUTHENTICATED"
}
}
| 理由 | HTTP ステータス コード | 説明 | トラブルシューティング |
|---|---|---|---|
unauthenticated |
401 |
次のいずれかの理由でリクエストの認証が失敗します。
|
OAuth またはアプリケーションのデフォルト認証情報を更新するか、サービス アカウントで実行またはサービス アカウントの権限を借用するときに |
403 - Forbidden
リクエストされたリソースにアクセスする権限がない場合に返されるエラー レスポンスの例を次に示します。
403 Forbidden
{
"error": {
"errors": [
{
"domain": "global",
"reason": "accessDenied",
"message": "Access Denied: Dataset myproject:mydataset: User does not have bigquery.datasets.get permission in project myproject."
}
],
"code": 403,
"message": "Access Denied: Dataset myproject:mydataset: User does not have bigquery.datasets.get permission in project myproject."
}
}
| 理由 | HTTP ステータス コード | 説明 | トラブルシューティング |
|---|---|---|---|
responseTooLarge |
403 |
クエリまたはテーブルの読み取りレスポンスが、次のいずれかの方法でサイズ上限を超えている。
エラーが返されます: |
宛先テーブルを指定し(レガシー SQL の場合は |
apiLimitExceeded |
403 |
リクエストが次のいずれかの API またはメタデータの上限を超えている。
エラーが返されます: |
切り捨て指数バックオフ、バッチ読み込み、読み取りを使用して失敗したリクエストを再試行し、テーブルごとのきめ細かい IAM ポリシーまたは行レベルのセキュリティ ポリシーを簡素化し、ローリング ウィンドウを待ってからデータセット レプリカを追加します。詳細については、API レートとメタデータ評価の上限エラーとクロスリージョン データセット レプリカの作成上限エラーをご覧ください。 |
quotaExceeded |
403 |
プロジェクトが次のいずれかの使用量割り当てを超えている。
エラーが返されます: |
エラー |
rateLimitExceeded |
403 |
リクエストは、次のいずれかのレート制限または同時実行制限のために拒否されます。
|
リクエスト率を下げて、切り捨て型指数バックオフを使用して再試行するか、バッチ優先度で緊急性の低いクエリを実行して、予約の同時実行数またはスロットの自動スケーリングを調整します。詳細については、割り当てと上限のエラーのトラブルシューティングとクエリの承認が拒否されたをご覧ください。 |
accessDenied |
403 |
次のいずれかの理由により、BigQuery リソースへのアクセスが拒否されます。
エラーが返されます: |
Cloud Audit Logs( |
policyViolation |
403 |
セキュリティ境界または組織のポリシーによってリクエストがブロックされている。
|
ログ エクスプローラを |
billingNotEnabled |
403 |
リクエストされたオペレーションに対して、プロジェクトで有効な課金が設定されていません。
エラーが返されます: |
Google Cloud コンソールでプロジェクトの課金を有効にして BigQuery サンドボックスからアップグレードし、テーブル、ビュー、パーティションのデフォルトの有効期限を更新します。詳細については、プロジェクトで課金が有効になっていないをご覧ください。 |
blocked |
403 |
BigQuery は、サービス停止を防ぐために、試行されたオペレーションを一時的に拒否リストに追加しました。エラーは |
正確なタイムスタンプ、プロジェクト ID、BigQuery ジョブ ID を添えて Cloud カスタマーケアにお問い合わせください。管理上の緩和ルールを調査します。詳細については、システム オペレーションを保護するためにリクエストがブロックされたをご覧ください。 |
termsOfServiceNotAccepted |
403 |
プロジェクトが BigQuery の利用規約に同意していません。エラーは |
Google Cloud コンソールにログインし、プロンプトが表示されたら、スタートページで国を選択して利用規約のチェックボックスをオンにし、[同意して続行] をクリックします。詳細については、BigQuery 利用規約が承認されていないをご覧ください。 |
404 - 見つかりません
存在しないデータセットまたはリソースを取得しようとしたときに返されるエラー レスポンスの例を次に示します。
404 Not Found
{
"error": {
"errors": [
{
"domain": "global",
"reason": "notFound",
"message": "Not Found: Dataset myproject:foo"
}
],
"code": 404,
"message": "Not Found: Dataset myproject:foo"
}
}
| 理由 | HTTP ステータス コード | 説明 | トラブルシューティング |
|---|---|---|---|
notFound |
404 |
リクエストされたリソースが見つからない理由は次のいずれかです。
エラーが返されます: |
大文字と小文字を区別するプロジェクト、データセット、テーブルの識別子とロケーションを正確に確認し、タイムトラベル ウィンドウ内で削除されたテーブルを復元します。キャッシュに保存された結果テーブルの有効期限が切れたクエリを再実行するか、外部の Cloud Storage または Google ドライブのファイルが存在することを確認します。詳細については、テーブルが見つからない、ロケーションが見つからない、ジョブが見つからないをご覧ください。 |
409 - Conflict
次の例は、すでに存在するリソースを作成しようとした場合に返されるエラー レスポンスです。
409 Conflict
{
"error": {
"errors": [
{
"domain": "global",
"reason": "duplicate",
"message": "Already Exists: Dataset myproject:mydataset"
}
],
"code": 409,
"message": "Already Exists: Dataset myproject:mydataset"
}
}
| 理由 | HTTP ステータス コード | 説明 | トラブルシューティング |
|---|---|---|---|
abortd |
409 |
同時変更または競合が原因でオペレーションが停止します(理由 |
競合するオペレーションが切り捨て型指数バックオフを使用して終了した後にオペレーションを再試行するか、停止したマルチステートメント トランザクションをロールバックしてから再試行します。詳細については、オペレーションが中止されたをご覧ください。 |
duplicate |
409 |
リクエストが既存のリソースと競合するのは、次のいずれかの場合です。
エラーが返されます: |
別のリソース名を使用するか、DDL ステートメントで |
499 - クライアントがリクエストを閉じました
| 理由 | HTTP ステータス コード | 説明 | トラブルシューティング |
|---|---|---|---|
stopped |
499 |
ジョブは、次のいずれかの理由で完了前に停止します(
エラーが返されます: |
|
500 - 内部サーバーエラー
| 理由 | HTTP ステータス コード | 説明 | トラブルシューティング |
|---|---|---|---|
internalError |
500 |
BigQuery で内部エラーが発生しました。エラーは次のとおりです。
|
BigQuery サービスレベル契約のバックオフ要件に沿って待機し、切り捨て指数バックオフを使用して再試行するか、予約を使用して一時的なエラーの頻度を減らします。詳細については、internalError エラーのトラブルシューティングをご覧ください。 |
501 - 未実装
| 理由 | HTTP ステータス コード | 説明 | トラブルシューティング |
|---|---|---|---|
notImplemented |
501 |
リクエストが、ターゲット リソースに対して実装されていない機能またはオペレーションを使用しようとしています。次に例を示します。
エラーが返されます: |
|
503 - サービス利用不可
| 理由 | HTTP ステータス コード | 説明 | トラブルシューティング |
|---|---|---|---|
backendError |
503 |
次のいずれかの理由により、サービスが一時的に利用できなくなっています。
エラーは |
切り捨て型指数バックオフを使用してリクエストを再試行し、失敗したジョブを新しい |