Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

エラーを解決する

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

ヘッダーの 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 フィールドを評価します。このエラーは、次のような状況で発生します。

アプリは認証済みユーザーのドメイン内で使用できません。
プロジェクトが 1 日の利用時間の上限を超えました。
ユーザーがレート制限を超えました。
プロジェクトがレート制限を超えました。

詳細については、使用量上限をご覧ください。

`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「Too many requests」エラーは、ユーザーごとの 1 日の上限（メール送信の上限を含む）、帯域幅の上限、ユーザーごとの同時リクエストの上限が原因で発生することがあります。各上限に関する情報は次のとおりです。ただし、各上限は、失敗したリクエストを再試行するか、複数の Gmail アカウントに処理を分割することで解決できます。

ユーザーあたりの上限を引き上げることはできません。上限の詳細については、使用量上限をご覧ください。

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

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

これらの上限はユーザー単位で、API クライアント、組み込みクライアント、ウェブクライアント、SMTP MSA など、ユーザーのすべてのクライアントで共有されます。これらの上限を超えると、API は HTTP 429 エラー「Too many requests: User-rate limit exceeded (Mail sending)（リクエストが多すぎます: ユーザーのレート上限を超えています（メール送信））」と再試行時間を返します。1 日あたりの上限を超えると、サーバーがリクエストを受け入れるまでに数時間エラーが発生する可能性があります。

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

帯域幅の上限

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

通常、ユーザーがこれらの上限に達するのは、例外的な状況や不正使用の場合のみです。これらの上限を超えると、API は HTTP 429「Too many requests: User-rate limit exceeded」エラーと再試行時間を返します。1 日あたりの上限を超えると、サーバーがリクエストを受け入れるまでに数時間、これらのエラーが発生する可能性があります。

同時要求

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

1 人のユーザーに対して多くの並列リクエストを行うか、リクエスト数の多いバッチを送信すると、このエラーがトリガーされる可能性があります。多数の独立した API クライアントが Gmail ユーザーのメールボックスに同時にアクセスした場合も、このエラーが発生することがあります。この上限を超えると、API は HTTP 429「リクエストが多すぎます: ユーザーに対する同時リクエストが多すぎます」というエラーを返します。

500、502、503、504 エラー

このエラーは、リクエストの処理中に予期しないサーバーエラーが発生した場合に発生します。これらのエラーの原因としては、リクエストのタイミングが別のリクエストと重複している、サポートされていないアクションのリクエスト（Google サイトのサイト全体ではなく、単一のページの権限を更新しようとしているなど）など、さまざまな問題が考えられます。

5xx エラーの一覧は次のとおりです。

500 バックエンドエラー
502 Bad Gateway
503 Service unavailable
504 Gateway timeout

`backendError`

このエラーは、リクエストの処理中に予期しないエラーが発生した場合に発生します。このエラーの JSON サンプルを次に示します。

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

このエラーを修正するには、指数バックオフを使用してリクエストを再試行します。

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

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

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

割り当て上限を管理

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

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

詳細については、割り当ての表示と管理をご覧ください。

バッチリクエスト

バッチリクエストはパフォーマンスを向上させることができますが、バッチサイズが大きいとレート制限がトリガーされる可能性があります。50 件を超えるリクエストのバッチは送信しないでください。リクエストをバッチ処理する方法については、リクエストのバッチ処理をご覧ください。

エラーを解決する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

HTTP ステータス コードの概要

400 エラー

badRequest