處理錯誤

歐洲經濟區 (EEA) 開發人員

提出要求後，您可能會收到包含錯誤詳細資料的回應。

2D 圖塊和街景服務圖像

下表列出使用 2D 圖塊和街景服務圖像時，可能會遇到的錯誤。

錯誤清單

下表列出使用 Map Tiles API 時可能遇到的錯誤。

required

要求缺少網址參數。請注意，錯誤訊息會指出缺少的參數。

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 金鑰。
訊息：Your request cannot be served. Please ensure the parameters and request type are valid for your account and region.

如果專案連結的帳單帳戶地址位於歐洲經濟區 (EEA)，則無法使用 2D 衛星圖塊。詳情請參閱「歐洲經濟區客戶適用的 Map Tiles API 調整」。

expired

您的 session 權杖已過期。工作階段符記的有效期限為建立後兩週。請注意，這項資訊可能隨時變動，恕不另行通知。如果收到這則錯誤訊息，請按照「使用工作階段符記」一節的說明，取得新的工作階段符記。

badRequest

要求格式錯誤，常見原因包括：

您指定了 terrain 地圖類型，但未加入 roadmap 圖層。
您為非路線圖的地圖類型加入了 styles 陣列。
您在街景服務中繼資料要求中，傳送了經緯度值和全景 ID。

quotaExceeded、rateLimitExceeded

應用程式已超過允許的配額，或超過每秒查詢次數上限。

錯誤示例

{
  "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 伺服器超載，因為許多用戶端會嘗試快速連續重試要求。也就是說，重試要求時，請使用指數輪詢。指數輪詢會強制您分散要求，讓伺服器有時間復原。

舉例來說，如果要求失敗，請在一秒後重試。但如果該嘗試也失敗，請在兩秒後再次重試要求。如果該要求也失敗，請在四秒後再試一次。因此，只要將每次要求之間的時間長度加倍，就能有效分散每次後續要求。

3D Tiles

Google 伺服器發生錯誤時，您可能不會察覺，因為您是透過轉譯器存取擬真 3D 圖塊，而轉譯器會負責處理伺服器錯誤。

圖塊轉譯器錯誤

舉例來說，CesiumJS 轉譯器通常會在發生伺服器錯誤時自動失敗，可能導致當機、空白畫面，或特定圖塊無法載入。

偵錯伺服器錯誤時，應根據使用的轉譯器，採取相應技術。如果是 CesiumJS 等瀏覽器型轉譯器，您可以使用大多數瀏覽器內建的工具檢查網路流量。舉例來說，您可以使用 Chrome 開發人員工具。

常見錯誤

以下列出您可能遇到的最常見錯誤。

400：引數無效: API 金鑰、查詢參數、圖塊/圖塊集 ID 無效，或工作階段權杖已過期。
400：值無效: 請確認發出 createSessionToken 要求的 mapType 與後續圖塊端點使用的 mapType 相符。舉例來說，streetview 工作階段符記無法用於要求 roadmap 圖塊。

403：權限遭拒