エラー処理

リクエストを送信すると、エラーの詳細を含むレスポンスが返されることがあります。

2D タイルおよびストリートビュー画像

次のリストは、2D タイルやストリートビュー画像の使用時に発生する可能性のあるエラーの詳細を示しています。

エラーのリスト

次のリストは、Map Tiles API の使用時に発生する可能性のあるエラーの詳細です。

required
リクエストに URL パラメータが欠落しています。エラー メッセージには、不足しているパラメータが示されます。
notFound、invalid

x、y、または z の値が範囲外です。

  • 通常のマップタイルの場合、最大ズームレベルは、特定のマップタイルとリクエストされたマップのオプションによって異なります。

  • 通常のマップタイルの場合、x 座標は [0, (2^zoom)-1] の範囲である必要があります。

  • 通常の地図タイルの場合、y 座標は [0, (2^(zoom-1))-1] の範囲にする必要があります。

  • ストリートビュー タイルでは、ズームは 0 ～ 5 の範囲である必要があります。

  • ストリートビュー タイルでは、ズームレベル 5 までは、x 座標と y 座標の範囲は通常の地図タイルと同じです。その時点での最大値は、imageHeight または imagewidth を tileHeight または tileWidth で除算した値です。

forbidden: リクエストに有効な API キーがありません。

expired
session トークンの有効期限が切れました。セッション トークンは、作成時点から 2 週間有効です。これは予告なく変更される場合があります。このエラーが発生した場合は、セッション トークンを使用するで説明されているように、新しいセッション トークンを取得する必要があります。
badRequest

リクエストの形式が正しくありません。一般的な理由には、以下のようなものがあります。

  • roadmap レイヤを含めずにマップタイプ terrain を指定しました。

  • 道路地図以外のマップタイプに styles 配列を含めています。

  • ストリートビュー メタデータ リクエストで緯度/経度の値とパノラマ ID を送信しました。

quotaExceeded、rateLimitExceeded

アプリケーションで、許容割り当てまたは 1 秒あたりのクエリ数を超過しています。

エラーの例

{
  "error": {
    "code": 403,
    "message": "The request is missing a valid API key.",
    "errors": [
      {
        "message": "The request is missing a valid API key.",
        "domain": "global",
        "reason": "forbidden"
      }
    ],
    "status": "PERMISSION_DENIED"
  }
}

リクエストの再試行

リクエストが quotaExceeded と rateLimitExceeded で失敗した場合は、多くのクライアントがリクエストを連続して再試行しようとするため、不完全なリクエストや広範な障害で Google のサーバーが処理不能にならないように、リクエストを再試行する必要があります。つまり、リクエストを再試行するときに指数バックオフを使用します。指数バックオフでは、サーバーが復旧する時間を確保するために、リクエストを時間的に分散する必要があります。

たとえば、リクエストが失敗した場合は、1 秒後に再試行します。それでも失敗した場合は、2 秒後にリクエストを再試行します。このリクエストも失敗した場合は、4 秒後にもう一度お試しください。つまり、リクエスト間の時間を 2 倍にすることで、連続するリクエストを効果的に分散できます。

3D タイル

レンダラを介してフォトリアリスティックなタイルにアクセスするため、Google のサーバーからのエラーが自明ではない可能性があります。レンダラはサーバーエラーを処理します。

タイルレンダラのエラー

たとえば、CesiumJS レンダラは通常、サーバーエラーが発生するとサイレント エラーが発生します。これにより、クラッシュ、空白の画面、特定のタイルが読み込まれないなどの問題が発生する可能性があります。

サーバーエラーのデバッグに使用する手法は、使用するレンダラによって異なります。CesiumJS などのブラウザベースのレンダラの場合、ほとんどのブラウザに組み込まれているツールを使用してネットワーク トラフィックを検査できます。たとえば、Chrome DevTools を使用できます。

一般的なエラー

発生する可能性のある一般的なエラーの詳細は次のとおりです。

400: 引数が無効です
無効な API キー、クエリ パラメータ、タイル/タイルセット ID、期限切れのセッション トークン。
403: 権限が拒否されました
API キーがない、SSL 接続がない、または API キーが 3D タイルの許可リストに追加されていない。Map Tiles API の 3D Tiles 機能の許可リストに登録するには、プロジェクト ID を Google サポートにご連絡ください。
429: リクエストが多すぎます
割り当てが使い切れました。割り当てを増やすには、Google サポートにお問い合わせください。