エラーを解決する

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「リクエストが多すぎます」エラーは、ユーザーあたりの 1 日の上限（メール送信の上限を含む）、帯域幅の上限、ユーザーあたりの同時リクエスト数の上限が原因で発生する可能性があります。各上限については、以下をご覧ください。ただし、各上限は、失敗したリクエストを再試行するか、複数の Gmail アカウントに処理を分割することで解決できます。

ユーザーあたりの上限は、いかなる理由でも増やすことはできません。上限について詳しくは、使用制限をご覧ください。

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

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

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

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

帯域幅に関する制限事項

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

通常、これらの上限は、例外的な状況や不正使用の場合にのみ発生します。これらの上限を超えると、再試行までの時間とともに HTTP 429「リクエストが多すぎます: ユーザーあたりのレート制限を超えました」エラーが返されます。1 日の上限を超えると、リクエストが受け入れられるまで数時間、これらのエラーが発生する可能性があります。

同時要求

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

1 人のユーザーに対して多くの並列リクエストを行う場合や、多数のリクエストを含むバッチを送信すると、このエラーが発生する可能性があります。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 ステータス コードの概要