解決錯誤

Gmail API 會傳回兩層的錯誤資訊：

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

使用 REST API 時，Gmail 應用程式應找出並處理所有可能發生的錯誤。本指南提供操作說明，協助您解決特定 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"
  }
}

如要修正這項錯誤，請使用長期有效的更新權杖重新整理存取權杖。如果您使用用戶端程式庫，系統會自動處理權杖重新整理。如果失敗，請按照「使用 Gmail 授權應用程式」一文所述，引導使用者完成 OAuth 流程。

如要進一步瞭解 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 會強制執行標準的每日郵件傳送上限。付費使用者和試用 gmail.com 使用者的限制不同。 Google Workspace 如要瞭解這些限制，請參閱「 Google Workspace 的 Gmail 傳送限制」。

這些限制適用於每位使用者，且所有使用者用戶端 (無論是 API 用戶端、原生/網路用戶端或 SMTP MSA) 都會共用這些限制。如果超過這些限制，系統會傳回 HTTP 429 Too Many Requests「User-rate limit exceeded」(超過使用者速率限制)「(Mail sending)」(郵件傳送) 錯誤，並顯示重試時間。請注意，如果超過每日限制，要求可能要過數小時才會獲准，期間可能會發生這類錯誤。

郵件傳送管道相當複雜，使用者一旦超出配額，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 個要求的批次。如要瞭解如何批次處理要求，請參閱批次處理要求。