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 エラーは、プロジェクトが特別の API 制限に達したことを示します。このエラーの JSON 表現は次のとおりです。
{
"error": {
"errors": [
{
"domain": "usageLimits",
"reason": "dailyLimitExceeded",
"message": "Daily Limit Exceeded"
}
],
"code": 403,
"message": "Daily Limit Exceeded"
}
}
このエラーを解決するには:
- Google API Console にアクセスします。
- プロジェクトを選択します。
- [割り当て] タブをクリックします。
- 追加の割り当てをリクエストします。詳細については、追加の割り当てをリクエストするをご覧ください。
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."
}
}
このエラーを解決するには:
- アプリが Gmail にアクセスすることがドメインで許可されていないことをユーザーに伝えます。
- ドメイン管理者にアプリのアクセス権をリクエストするようユーザーに指示します。
429 エラーの解決: リクエストが多すぎます
429「リクエストが多すぎます」エラーは、ユーザーごとの 1 日あたりの上限（メール送信の上限を含む）、帯域幅の上限、またはユーザーごとの同時リクエストの上限が原因で発生することがあります。各上限に関する情報は次のとおりです。ただし、失敗したリクエストを再試行するか、複数の Gmail アカウント間で処理を分割することで、それぞれの上限を解決できます。理由を問わず、ユーザーごとの上限を引き上げることはできません。上限の詳細については、使用量上限をご覧ください。
メール送信に関する制限事項
Gmail API では、標準的な 1 日あたりのメール送信制限が適用されます。これらの上限は、有料ユーザーと Google Workspace 試用版 gmail.com ユーザーで異なります。これらの上限については、 Google Workspaceでの Gmail の送信制限をご覧ください。
これらの上限はユーザーごとに適用され、API クライアント、ネイティブ/ウェブ クライアント、SMTP MSA など、ユーザーのすべてのクライアントで共有されます。これらの上限を超えると、HTTP 429 Too Many Requests "User-rate limit exceeded"
"(Mail sending) エラーが再試行時間とともに返されます。1 日の上限を超えると、リクエストが承認されるまで数時間にわたって、この種のエラーが発生する可能性があります。
メール送信パイプラインは複雑です。ユーザーが割り当てを超過した後、API が 429 エラー レスポンスを返し始めるまでに数分かかる場合があります。そのため、200 レスポンスがメールが正常に送信されたことを意味するわけではありません。
帯域幅の上限
この API では、ユーザーごとのアップロードとダウンロードの帯域幅の上限が、IMAP と同等ですが、IMAP とは独立しています。これらの上限は、各ユーザーのすべての Gmail API クライアントで共有されます。
通常、これらの上限に達するのは、例外的な状況または不正な状況下に限られます。これらの上限を超えると、HTTP 429 Too Many Requests「User-rate limit exceeded」というエラーが再試行時間とともに返されます。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 秒後に再試行期間を開始します。
使用量上限を確認または変更する、割り当てを増やす
プロジェクトの使用量上限を確認して変更する手順、または割り当ての増加をリクエストする手順は次のとおりです。
- プロジェクトの請求先アカウントをまだ保有していない場合は、アカウントを作成します。
- API Console で API ライブラリの [有効な API] ページに移動し、リストから API を選択します。
- 割り当て関連の設定を表示および変更するには、[割り当て] を選択します。使用統計情報を表示するには、[使用量] を選択します。
バッチ リクエスト
バッチ処理の使用をおすすめしますが、バッチサイズを大きくするとレート制限がトリガーされる可能性があります。50 件を超えるリクエストを一括で送信することはおすすめしません。リクエストをバッチ処理する方法については、リクエストのバッチ処理をご覧ください。