本頁面由 Cloud Translation API 翻譯而成。

處理錯誤

歐洲經濟區 (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 之間 (含首尾)。
對於街景服務圖塊，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 adjustments for EEA customers」。

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 圖塊

您是透過負責處理伺服器錯誤的算繪器存取擬真圖塊，因此可能不會發現 Google 伺服器發生錯誤。

圖塊轉譯器錯誤

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

您用來偵錯伺服器錯誤的技術，取決於您使用的特定轉譯器。如果是以瀏覽器為基礎的算繪器 (例如 CesiumJS)，您可以使用大多數瀏覽器內建的工具檢查網路流量。舉例來說，您可以使用 Chrome 開發人員工具。

常見錯誤

以下列出您可能會遇到的常見錯誤，並提供詳細資訊。

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

403：權限遭拒