解決錯誤

Gmail API 會傳回兩種層級的錯誤資訊:

  • 標頭中的 HTTP 錯誤代碼和訊息。
  • 回應主體中的 JSON 物件,其中包含其他詳細資料,可協助您判斷如何處理錯誤。

Gmail 應用程式應找出並處理使用 REST API 時可能遇到的所有錯誤。本指南將說明如何解決特定 API 錯誤。

解決 400 錯誤:錯誤的要求

這個錯誤可能是由程式碼中的以下錯誤所造成:

  • 未提供必要欄位或參數。
  • 提供的值或提供欄位的組合無效。
  • 附件無效。

以下是這個錯誤的 JSON 表示法範例:

{
  "error": {
    "code": 400,
    "errors": [
      {
        "domain": "global",
        "location": "orderBy",
        "locationType": "parameter",
        "message": "Sorting is not supported for queries with fullText terms. Results are always in descending relevance order.",
        "reason": "badRequest"
      }
    ],
    "message": "Sorting is not supported for queries with fullText terms. Results are always in descending relevance order."
  }
}

如要修正這項錯誤,請檢查 message 欄位,並據此調整程式碼。

解決 401 錯誤:憑證無效

401 錯誤表示您使用的存取權杖已到期或無效。這項錯誤也可能源自於缺少所要求的範圍授權。以下是這項錯誤的 JSON 表示法:

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "authError",
        "message": "Invalid Credentials",
        "locationType": "header",
        "location": "Authorization",
      }
    ],
    "code": 401,
    "message": "Invalid Credentials"
  }
}

如要修正這項錯誤,請使用長期有效的更新憑證重新整理存取權杖。如果您使用的是用戶端程式庫,系統會自動處理權杖重新整理作業。如果這項操作失敗,請引導使用者透過 OAuth 流程進行操作,詳情請參閱「使用 Gmail 授權應用程式」一文。

如要進一步瞭解 Gmail 限制,請參閱「用量限制」。

解決 403 錯誤:超過用量限制

如果使用者超出使用限制,或沒有正確的權限,就會發生錯誤 403。如要判斷錯誤的具體類型,請評估傳回 JSON 的 reason 欄位。發生此錯誤的情況如下:

  • 超過每日上限。
  • 超過使用者頻率限制。
  • 超過專案頻率限制。
  • 您的應用程式無法在已驗證使用者的網域中使用。

如要進一步瞭解 Gmail 限制,請參閱「用量限制」。

解決 403 錯誤:超過每日限制

dailyLimitExceeded 錯誤表示專案已達免費 API 限制。以下是這項錯誤的 JSON 表示法:

{
  "error": {
    "errors": [
      {
        "domain": "usageLimits",
        "reason": "dailyLimitExceeded",
        "message": "Daily Limit Exceeded"
      }
    ],
    "code": 403,
    "message": "Daily Limit Exceeded"
  }
}

如要修正這項錯誤:

  1. 前往 Google API 控制台
  2. 選取專案。
  3. 按一下「配額」分頁標籤
  4. 要求額外配額。詳情請參閱「申請更多配額」。

如要進一步瞭解 Gmail 限制,請參閱「用量限制」。

解決 403 錯誤:超過使用者頻率限制

userRateLimitExceeded 錯誤表示已達到每位使用者限制。以下是這項錯誤的 JSON 表示法:

{
 "error": {
  "errors": [
   {
    "domain": "usageLimits",
    "reason": "userRateLimitExceeded",
    "message": "User Rate Limit Exceeded"
   }
  ],
  "code": 403,
  "message": "User Rate Limit Exceeded"
 }
}

如要修正這項錯誤,請嘗試最佳化應用程式程式碼,以減少要求或重試要求的次數。如要瞭解如何重試要求,請參閱「重試失敗的要求以解決錯誤」。

如要進一步瞭解 Gmail 限制,請參閱「用量限制」。

解決 403 錯誤:超過頻率限制

rateLimitExceeded 錯誤表示使用者已達到 Gmail API 的最大要求率。這項限制會因要求類型而異。以下是這項錯誤的 JSON 表示法:

{
 "error": {
  "errors": [
   {
    "domain": "usageLimits",
    "message": "Rate Limit Exceeded",
    "reason": "rateLimitExceeded",
   }
  ],
  "code": 403,
  "message": "Rate Limit Exceeded"
 }
}

如要修正這項錯誤,請重試失敗的要求

如要進一步瞭解 Gmail 限制,請參閱「用量限制」。

解決 403 錯誤:無法在已驗證使用者的網域中使用 ID 為 {appId} 的應用程式

如果使用者網域的政策不允許應用程式存取 Gmail,就會發生 domainPolicy 錯誤。以下是這項錯誤的 JSON 表示法:

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "domainPolicy",
        "message": "The domain administrators have disabled Gmail apps."
      }
    ],
    "code": 403,
    "message": "The domain administrators have disabled Gmail apps."
  }
}

如要修正這項錯誤:

  1. 請告知使用者,該網域不允許應用程式存取 Gmail。
  2. 請使用者與網域管理員聯絡,要求對方授予應用程式存取權。

解決 429 錯誤:要求數量過多

由於每日使用者限制 (包括郵件傳送限制)、頻寬限制或使用者並行要求限制,因此可能會發生 429「要求次數過多」錯誤。以下是各項限制的相關資訊。不過,您可以嘗試重試失敗的要求,或將處理作業分散到多個 Gmail 帳戶,以解決每項限制。無論任何原因,都無法提高每位使用者限制。如要進一步瞭解限制,請參閱「用量限制」。

郵件傳送限制

Gmail API 會強制執行標準的每日郵件傳送限制。付費 Google Workspace 使用者和試用版 gmail.com 使用者的限制不同。如要瞭解這些限制,請參閱「 Google Workspace的 Gmail 傳送限制」。

這些限制適用於每位使用者,且由所有使用者的用戶端共用,無論是 API 用戶端、原生/網頁用戶端或 SMTP MSA 皆是如此。如果超過這些限制,系統會傳回 HTTP 429 Too Many Requests「User-rate limit exceeded」(郵件傳送) 錯誤,並附上重試時間。請注意,如果超過每日限制,可能會在要求接受前,連續數小時發生這類錯誤。

郵件傳送管道相當複雜:一旦使用者超出配額,API 可能需要延遲數分鐘才會開始傳回 429 錯誤回應。因此,您不能假設 200 回應代表電子郵件已順利傳送。

頻寬限制

API 設有個別使用者的上傳和下載 頻寬限制,與 IMAP 相同,但彼此獨立。這些限制適用於特定使用者的所有 Gmail API 用戶端。

這些限制通常只會在特殊或濫用情況下觸發。如果超過這些限制,系統會傳回 HTTP 429 Too Many Requests「User-rate limit exceeded」錯誤訊息,並附上重試時間。請注意,如果超過每日限制,可能會導致這類錯誤持續數小時,直到要求獲得接受為止。

並行要求

Gmail API 會強制執行每位使用者的並行要求限制 (除了每位使用者的頻率限制)。所有存取特定使用者的 Gmail API 用戶端都會共用這項限制,確保沒有 API 用戶端會對 Gmail 使用者信箱或其後端伺服器造成過載。

為單一使用者提出多個並行要求,或傳送包含大量要求的批次,都可能觸發此錯誤。大量獨立的 API 用戶端同時存取 Gmail 使用者信箱,也會觸發這項錯誤。如果超過此上限,系統會傳回 HTTP 429 Too Many Requests「Too many concurrent requests for user」(使用者的並行要求數超量) 錯誤。

解決 500 錯誤:後端錯誤

處理要求時發生未預期的錯誤,就會發生 backendError

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "backendError",
    "message": "Backend Error",
   }
  ],
  "code": 500,
  "message": "Backend Error"
 }
}

如要修正這項錯誤,請重試失敗的要求。以下是 500 個錯誤的清單:

  • 502 閘道錯誤
  • 503 服務無法使用
  • 504 閘道逾時

重新嘗試提出要求以解決錯誤

您可以定期重試失敗的要求,並逐漸增加重試次數,以處理與速率限制、網路量或回應時間相關的錯誤。舉例來說,您可以在一秒後、兩秒後,然後在四秒後重試失敗的要求。這種方法稱為「指數輪詢」,可用於改善頻寬使用情形,並在並行環境中盡可能提高要求的總處理量。

在錯誤發生後至少等待一秒,再開始重試週期。

查看或變更用量限制、增加配額

如要查看或變更專案的用量限制,或是想申請更多配額,請進行以下步驟:

  1. 確認您的專案已設有帳單帳戶。如果沒有,請先建立一個。
  2. 開啟 API 控制台並前往 API 程式庫「已啟用的 API」頁面,從清單中選取 API。
  3. 如要查看及變更配額相關設定,請點選「配額」。如要查看用量統計資料,請點選「用量」

批次要求

我們建議使用批次處理,但較大的批次大小可能會觸發速率限制。不建議傳送超過 50 個要求的批次。如要瞭解如何批次要求,請參閱「批次要求」。