Maps Static API 中的錯誤訊息

Maps Static API 可能會在發生問題時發出錯誤或警告 錯誤。本指南會說明各項錯誤訊息,並進一步說明 以及修正錯誤的操作說明。

無效請求

如果要求無效,Maps Static API 會傳回 HTTP 4xx 狀態碼,並傳回描述問題的訊息。以下是這類錯誤狀態的範例。注意:這並非 所有可能錯誤的完整清單。如要瞭解特定問題的詳細資訊,請查看 API 傳回的實際錯誤代碼和訊息。

錯誤狀況示例 狀態碼
請求包含無效參數,或必要參數為 舉例來說,size 參數不在 未預期的數值範圍,或是要求中缺少值。 400 BAD REQUEST
要求中的 API 金鑰無效。 403 FORBIDDEN

導致地圖無法顯示的錯誤

如果要求有效,但發生其他錯誤而導致地圖無法顯示,則 Maps Static API 會傳回文字或錯誤圖片,而非地圖,具體取決於錯誤。這類錯誤的例子 條件是當應用程式超出 用量限制

顯示錯誤圖片而非地圖
圖:顯示錯誤圖片,而非地圖

如果您在沒有 API 金鑰或計費的情況下使用 Maps Static API 帳戶尚未啟用,頁面會顯示錯誤圖片,而非 ,並用連結指出錯誤類型。例如「g.co/staticmaperror/key」。

無金鑰錯誤和解決方案
使用限制錯誤:已超過提供的每日地圖載入上限 您正在使用 Maps Static API,但沒有 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 網頁控制台或其他同等工具,即可在瀏覽器中使用。