解決錯誤

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

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

Gmail 應用程式應會擷取並處理使用 REST API 時可能遇到的所有錯誤。本指南提供相關操作說明，協助您解決特定 Gmail API 錯誤。

HTTP 狀態碼摘要

錯誤代碼	說明
`200 - OK`	要求成功 (這是成功 HTTP 要求的標準回應)。
`400 - Bad Request`	要求發生用戶端錯誤，因此無法完成。
`401 - Unauthorized`	要求中包含無效的憑證。
`403 - Forbidden`	系統已收到並瞭解要求，但使用者沒有執行要求的權限。
`404 - Not Found`	找不到要求的頁面。
`429 - Too Many Requests`	對 API 發出的要求過多。
`500, 502, 503, 504 - Server Errors`	處理要求時發生未預期的錯誤。

400 錯誤

這類錯誤表示要求有誤，通常是因為缺少必要參數。

`badRequest`

如果程式碼發生下列任一問題，就可能導致這項錯誤：

缺少必填欄位或參數。
提供的值或提供的欄位組合無效。
附件無效。

以下 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 錯誤

這類錯誤表示要求未包含有效存取權杖。

`authError`

如果使用的存取權杖過期或無效，就會發生這個錯誤。如果缺少所要求範圍的授權，也可能導致這項錯誤。以下 JSON 範例代表這項錯誤：

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

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

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

403 錯誤

如果超出用量限制，或使用者沒有正確的權限，就會發生這些錯誤。如要判斷原因，請評估傳回的 JSON 中的 reason 欄位。發生這項錯誤的原因如下：

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

詳情請參閱「用量限制」。

`dailyLimitExceeded`

如果專案達到 API 限制，就會發生這個錯誤。以下 JSON 範例代表這項錯誤：

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

如果應用程式擁有者已設定配額上限，限制特定資源的使用量，就會顯示這則錯誤訊息。如要修正這項錯誤，請提高 Google Cloud 專案的配額。詳情請參閱「管理配額限制」。

`domainPolicy`

如果使用者網域的政策不允許應用程式存取 Gmail，就會發生這個錯誤。以下 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."
  }
}

如要修正這項錯誤，請嘗試下列步驟：

告知使用者網域不允許應用程式存取 Gmail。
請使用者與網域管理員聯絡，要求授予應用程式存取權。

`rateLimitExceeded`

這項錯誤表示使用者已達到 Gmail API 的要求速率上限。這項限制會因要求類型而異。以下 JSON 範例代表這項錯誤：

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

如要修正這項錯誤，請嘗試下列步驟：

申請提高配額。
使用指數輪詢重試要求。

`userRateLimitExceeded`

如果已達個別使用者限制，就會發生這個錯誤。以下 JSON 範例代表這項錯誤：

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

如要修正這項錯誤，請嘗試最佳化應用程式程式碼，減少要求數量，或使用指數輪詢重試要求。

429 錯誤

如果超過每日單一使用者限制 (包括郵件傳送限制)、頻寬限制或單一使用者並行要求限制，就可能發生 429「要求過多」錯誤。以下是各項限制的相關資訊。不過，您可以重試失敗的要求，或將處理作業分散到多個 Gmail 帳戶，解決各項限制。

無論如何，每位使用者的限制都無法提高。如要進一步瞭解限制，請參閱「用量限制」。

郵件傳送限制

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

這些限制適用於每位使用者，且所有使用者用戶端 (無論是 API 用戶端、內建或網頁用戶端，還是 SMTP MSA) 都會共用這些限制。如果超過這些限制，系統會傳回 HTTP 429「要求數過多：超過使用者速率限制 (郵件傳送)」錯誤，並提供重試時間。如果超過每日上限，系統可能會在數小時內拒絕要求，直到配額重置為止。

郵件傳送管道相當複雜，使用者超過配額後，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「要求數超量：使用者並行要求數過多」錯誤。

500、502、503、504 錯誤

處理要求時發生未預期的伺服器錯誤，就會出現這些錯誤。造成這些錯誤的原因有很多，包括要求時間與其他要求重疊，或是要求執行不支援的動作，例如嘗試更新 Google 協作平台中單一網頁的權限，而非整個網站。

以下列出 5xx 錯誤：

500 後端錯誤
502 閘道錯誤
503 無法使用服務
504 閘道逾時

backendError

處理要求時發生未預期的錯誤，就會出現這個錯誤。以下 JSON 範例代表這項錯誤：

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

如要修正這項錯誤，請使用指數輪詢重試要求。

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

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

請在發生錯誤後至少一秒再開始重試。

管理配額限制

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

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

詳情請參閱「查看及管理配額」。

批次要求

建議使用批次要求，但批次大小過大可能會觸發頻率限制。不建議傳送超過 50 個要求的批次。如要瞭解如何提出批次要求，請參閱「批次要求」一文。