解決錯誤

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「超過使用者費率限制」「(郵件傳送)」錯誤，並提供重試的時間。請注意，如果超過每日限制，可能會導致這類錯誤持續數小時到接受要求為止。

郵件傳送管道相當複雜：使用者超過配額後，API 可能會延遲幾分鐘，才會開始傳回 429 錯誤回應。因此，您無法假設 200 回應代表電子郵件傳送成功。

頻寬限制

API 有每位使用者上傳及下載頻寬限制，這些限制與 IMAP 無關。這些限制適用於特定使用者的所有 Gmail API 用戶端。

一般而言，這些限制只有在特殊或濫用的情況下才會解除。如果超過 HTTP 429 Too Many Requests 系統會傳回「超過使用者頻率限制」錯誤訊息，並重試重試。請注意，超過每日限制可能會導致這類錯誤持續數小時後，系統才會接受要求。

並行要求

Gmail API 除了每位使用者的「頻率」限制外，也會強制執行每位使用者並行要求限制。此限制由存取特定使用者的所有 Gmail API 用戶端都共用，可確保 Gmail 使用者信箱或後端伺服器不會超載。

對單一使用者發出多項平行要求，或傳送大量要求時，可能會觸發這個錯誤。許多獨立 API 用戶端同時存取 Gmail 使用者信箱，也可能會觸發這個錯誤。如果超過這項限制，則系統會傳回「使用者並行要求過多」錯誤。Too Many Requests

解決 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 項要求。如要瞭解如何批次處理要求，請參閱批次處理要求。