Maps Static API 中的錯誤訊息

發生錯誤時，Maps Static API 可能會發出錯誤或警告。本指南會說明每則錯誤訊息，並提供進一步的錯誤解決指示。

無效的要求

如果要求無效，Maps Static API 會傳回 HTTP 4xx 狀態碼，並傳回描述問題的訊息。以下是這類錯誤狀態的範例。注意：這份清單僅列出部分可能的錯誤。如要瞭解特定問題的詳細資訊，請查看 API 傳回的實際錯誤代碼和訊息。

錯誤狀況範例 狀態碼
要求含有無效參數，或缺少必要參數。例如，size 參數不在預期的數值範圍內，或是在要求中缺少該參數。 400 BAD REQUEST
要求中包含的 API 金鑰無效。 403 FORBIDDEN

導致地圖無法顯示的錯誤

如果要求有效，但發生其他錯誤而導致地圖無法顯示，則 Maps Static API 會傳回文字或錯誤圖片，而非地圖，具體取決於錯誤。舉例來說，如果應用程式超過用量限制，就會發生這種錯誤。

顯示錯誤圖片，而非地圖
圖：顯示錯誤圖片，而非地圖

如果您在使用 Maps Static API 時未提供 API 金鑰，或是帳戶未啟用帳單功能，頁面會顯示錯誤圖片，而非地圖，並附上指出錯誤類型的連結。例如「g.co/staticmaperror/key」。

無鑰車門鎖錯誤和解決方法
使用限制錯誤：超過提供的每日地圖載入次數限制 您未使用 API 金鑰，就使用 Maps Static API。如要解決問題，您必須：
  1. 取得 API 金鑰
  2. 啟用計費功能
  3. 簽署網址
用量限制錯誤：要求網址缺少數位簽名 您的要求缺少數位簽名 (必要)。如要解決這個問題，請 簽署網址

警告

在某些錯誤情況下，API 會傳回地圖，但地圖可能會缺少部分資訊。發生這種情況時，系統會在兩種情況下通知您警告。

  • 一張地圖會顯示，但地圖頂端會疊加黃色錯誤列，並顯示「地圖錯誤：g.co/staticmaperror」文字。
  • 其次，API 會以名為 X-Staticmap-API-Warning 的 HTTP 標頭格式傳回警告。

舉例來說，下列網址的 markers 參數中包含非預期的值：

https://maps.googleapis.com/maps/api/staticmap?center=Williamsburg,Brooklyn,NY&zoom=13&scale=1&size=400x400&markers=sdgaags&key=YOUR_API_KEY

API 會傳回地圖，但會在圖片上方顯示黃色錯誤列，並顯示「地圖錯誤：g.co/staticmaperror」：

地圖顯示，但出現地圖錯誤：g.co/staticmaperror

API 也會傳回下列 HTTP 標頭：

X-Staticmap-API-Warning:Error geocoding: marker 1

下表說明 API 可能會以 HTTP 標頭形式發出的警告：

X-Staticmap-API-Warning 標頭中的警告
Error geocoding: [center, ][marker #number, ][visible #num, ][path #num, ]* 嘗試對要求進行地理編碼時發生錯誤，這則訊息有多種變化版本，取決於地理編碼失敗的元素 (中心、標記、可見或路徑) 和失敗元素的數量。這類警告的一個例子是 X-Staticmap-API-Warning:Error geocoding: marker 1，如上例所示。
Too many geocoded markers requested (max is 15). 要求中指定的標記數量超過允許的上限，且標記含有人可讀的地址。上限為 15 個。請注意，這項限制僅適用於指定為需要地理編碼的一般地址標記。不適用於以經緯度座標指定的標記。
Too many geocoded polyline vertices requested (max is 15). 要求中指定的多邊形線條數量超過人類可讀地址的允許上限。上限為 15 個。請注意，這項限制僅適用於邊界點指定為需要地理編碼的易讀地址的折線。不適用於以經緯度座標指定的折線。

您可以在 Chrome 開發人員工具控制台、Firefox 網頁控制台或瀏覽器中的其他同類工具中查看 HTTP 標頭警告。