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「Too many requests」エラーは、ユーザーごとの 1 日あたりの上限（メール送信の上限を含む）、帯域幅の上限、ユーザーごとの同時リクエストの上限が原因で発生することがあります。各上限に関する情報は次のとおりです。ただし、各上限は、失敗したリクエストの再試行を試すか、複数の Gmail アカウントに処理を分割することで解決できます。ユーザーあたりの制限は、いかなる理由でも引き上げることはできません。上限の詳細については、使用量上限をご覧ください。
メール送信に関する制限事項
Gmail API では、1 日あたりのメール送信数の標準的な上限が適用されます。これらの上限は、有料の ユーザーと試用版の gmail.com ユーザーで異なります。これらの上限については、 における 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「ユーザーの同時リクエストが多すぎます」というエラーが返されます。
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 つ作成します。
- API Console で API ライブラリの [有効な API] ページに移動し、リストから API を選択します。
- 割り当て関連の設定を表示および変更するには、[割り当て] を選択します。使用統計情報を表示するには、[使用量] を選択します。
バッチ リクエスト
バッチ処理の使用をおすすめしますが、バッチサイズが大きいとレート制限がトリガーされる可能性があります。50 件を超えるリクエストを含むバッチを送信することはおすすめしません。リクエストをバッチ処理する方法については、リクエストのバッチ処理をご覧ください。