Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

解決錯誤

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

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

使用 REST API 時，Gmail 應用程式應會擷取並處理您遇到的所有錯誤。本指南提供操作說明，協助您解決特定 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) 都會共用這些限制。如果超過這些限制，API 會傳回 HTTP 429「要求數過多：超出使用者速率限制 (郵件傳送)」錯誤，並提供重試時間。超過每日上限可能會導致伺服器在數小時內無法接受要求，並顯示下列錯誤訊息。

郵件傳送管道相當複雜，使用者一旦超過配額，API 可能要過幾分鐘才會開始傳回 429 錯誤回應。請勿假設 200 回應表示電子郵件已順利傳送。

頻寬限制

API 的上傳和下載頻寬限制與 IMAP 相同，但彼此獨立。使用者所有 Gmail API 用戶端共用這些限制。

使用者通常只會在特殊或濫用情況下遇到這些限制。如果超出這些限制，API 會傳回 HTTP 429「Too many requests: User-rate limit exceeded」(要求過多：超出使用者速率限制) 錯誤，並提供重試時間。如果超過每日上限，伺服器可能要過幾小時才會接受要求，期間可能會發生這些錯誤。

並行要求

Gmail API 會強制執行個別使用者的並行要求限制 (除了個別使用者的速率限制外)。所有存取使用者的 Gmail API 用戶端都會共用這項限制，確保沒有任何 API 用戶端會造成 Gmail 使用者信箱或後端伺服器過載。

如果為單一使用者提出大量並行要求，或傳送包含大量要求的批次，就可能觸發這項錯誤。如果大量獨立 API 用戶端同時存取 Gmail 使用者信箱，也可能觸發這項錯誤。如果超出這項限制，API 會傳回 HTTP 429「Too many requests: Too many concurrent requests for user」錯誤。

500、502、503、504 錯誤

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

以下列出 5xx 錯誤：

500 後端錯誤
502 Bad gateway
503 無法提供服務
504 閘道逾時

`backendError`

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

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

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

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

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

錯誤發生後，至少要過一秒才能開始重試。

管理配額限制

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

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

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

批次要求

批次要求可以提升效能，但如果批次大小過大，可能會觸發速率限制。請勿傳送超過 50 個要求的批次。如要瞭解如何批次處理要求，請參閱「批次要求」。