エラーを解決する。

Gmail API は、2 つのレベルのエラー情報を返します。

  • ヘッダーの 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"
  }
}

このエラーを修正するには、有効期間の長い更新トークンを使用してアクセス トークンを更新します。クライアント ライブラリを使用している場合、トークンの更新は自動的に処理されます。これが失敗した場合は、Gmail でアプリを承認するで説明されているように、ユーザーに OAuth フローを案内します。

Gmail の制限について詳しくは、使用制限をご覧ください。

403 エラー: 使用制限の超過を解決する

エラー 403 は、使用上限を超えた場合や、ユーザーに適切な権限がない場合に発生します。特定のエラータイプを特定するには、返された JSON の reason フィールドを評価します。このエラーは、次のような状況で発生します。

  • 1 日の上限を超えました。
  • ユーザーのデータ処理の上限を超えました。
  • プロジェクトのレート制限を超えました。
  • 認証されたユーザーのドメイン内でアプリを使用できません。

Gmail の制限について詳しくは、使用制限をご覧ください。

403 エラー: 1 日の上限を超えた

dailyLimitExceeded エラーは、プロジェクトの Courtesy API の上限に達したことを示します。このエラーの JSON 表現は次のとおりです。

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

このエラーを解決するには:

  1. Google API Console にアクセスします。
  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} のアプリは、認証されたユーザーのドメイン内で使用できません

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."
  }
}

このエラーを解決するには:

  1. ドメインでアプリが Gmail にアクセスできないことをお客様に伝えます。
  2. ドメイン管理者に連絡してアプリのアクセス権をリクエストするよう、ユーザーに伝えます。

429 エラー: リクエストが多すぎるを解決する

429「リクエストが多すぎます」エラーは、1 日あたりのユーザーごとの上限（メール送信の上限など）、帯域幅の上限、ユーザーごとの同時リクエストの上限が原因で発生することがあります。各上限に関する情報は次のとおりです。ただし、各上限は、失敗したリクエストを再試行するか、複数の Gmail アカウントに処理を分割することで解決できます。ユーザーごとの制限は、いかなる理由でも増やすことはできません。上限の詳細については、使用量の上限をご覧ください。

メール送信に関する制限事項

Gmail API では、1 日あたりのメール送信数の標準の上限が適用されます。これらの上限は、有料ユーザーと Gmail.com のトライアル ユーザーで異なります。 Google Workspace これらの上限については、 Google Workspaceにおける Gmail の送信制限をご覧ください。

これらの上限はユーザーごとで、API クライアント、ネイティブ/ウェブ クライアント、SMTP MSA など、ユーザーのすべてのクライアントで共有されます。これらの上限を超えると、HTTP 429 Too Many Requests「ユーザーレートの上限を超えました」"（メール送信）"というエラーが、再試行までの時間とともに返されます。1 日あたりの上限を超えると、リクエストが承認されるまでに数時間かかることがあります。

メール送信パイプラインは複雑です。ユーザーが割り当てを超えると、API が 429 エラー レスポンスを返すまでに数分かかることがあります。したがって、200 レスポンスがメールが正常に送信されたことを意味するとは限りません。

帯域幅の上限

この API には、IMAP と同等のユーザーごとのアップロードとダウンロードの帯域幅制限がありますが、IMAP とは独立しています。これらの上限は、特定のユーザーのすべての Gmail API クライアントで共有されます。

通常、これらの上限に達するのは、例外的な状況や不正行為が発生した場合のみです。これらの上限を超えると、HTTP 429 Too Many Requests「ユーザーレートの上限を超えました」エラーが返され、再試行までの時間が示されます。1 日あたりの上限を超えると、リクエストが承認されるまでに数時間かかることがあります。

同時要求

Gmail API には、ユーザーごとの同時リクエストの上限（ユーザーごとのレートの上限に加えて）があります。この上限は、特定のユーザーにアクセスするすべての Gmail API クライアントで共有され、API クライアントが Gmail ユーザーのメールボックスまたはバックエンド サーバーに過負荷をかけないようにします。

1 人のユーザーに対して多くの並列リクエストを実行したり、多数のリクエストを含むバッチを送信したりすると、このエラーが発生することがあります。多数の独立した 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 Bad Gateway（不正なゲートウェイ）
  • 503 Service Unavailable（サービス利用不可）
  • 504 Gateway Timeout（ゲートウェイ タイムアウト）

失敗したリクエストを再試行してエラーを解決する

レート制限、ネットワーク ボリューム、レスポンス時間に関連するエラーを処理するには、失敗したリクエストを定期的に再試行し、時間の経過とともに再試行間隔を長くします。たとえば、失敗したリクエストを 1 秒後に再試行し、2 秒後に再試行し、4 秒後に再試行します。この方法は指数バックオフと呼ばれ、同時実行環境で帯域幅の使用量を改善し、リクエストのスループットを最大化するために使用されます。

エラー発生後 1 秒以上経過してから再試行期間を開始します。

使用量上限の表示または変更、割り当ての増加

プロジェクトの使用量上限を確認して変更する手順、または割り当ての増加をリクエストする手順は次のとおりです。

  1. プロジェクトの請求先アカウントをまだ持っていない場合は、1 つ作成します。
  2. API Console で API ライブラリの [有効な API] ページに移動し、リストから API を選択します。
  3. 割り当て関連の設定を表示および変更するには、[割り当て] を選択します。使用統計情報を表示するには、[使用量] を選択します。

バッチ リクエスト

バッチ処理を使用することをおすすめしますが、バッチサイズが大きいほどレート制限がトリガーされる可能性があります。50 件を超えるリクエストのバッチを送信することはおすすめしません。リクエストをバッチ処理する方法については、リクエストのバッチ処理をご覧ください。