エラー レスポンス

標準エラー レスポンス

Real Time Reporting API リクエストの処理に成功すると、API は 200 HTTP ステータス コードとリクエストされたデータを含むレスポンス本文を返します。

リクエストでエラーが発生すると、API はエラーのタイプに基づき、HTTP ステータス コードと理由を含むレスポンスを返します。また、レスポンス本文にエラーの原因についての詳しい説明が記述されます。以下に、エラー レスポンスの例を示します。

400 invalidParameter

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "invalidParameter",
    "message": "Invalid value '-1' for max-results. Value must be within the range: [1, 1000]",
    "locationType": "parameter",
    "location": "max-results"
   }
  ],
  "code": 400,
  "message": "Invalid value '-1' for max-results. Value must be within the range: [1, 1000]"
 }
}

: 説明は常に変更される可能性があるため、アプリケーションを実際の説明テキストに依拠させないでください。

次のリストは、発生し得るエラーコード、理由、対応する説明、推奨される対処方法をまとめたものです。

コード 理由 説明 推奨される対処方法
400 invalidParameter リクエストのパラメータの値が無効であることを示します。エラー レスポンスの locationType フィールドと location フィールドに、どの値が無効であるかの情報が示されます。 問題を解決してから再試行してください。エラー レスポンスで指定されたパラメータに有効な値を指定する必要があります。
400 badRequest クエリが無効であることを示します。たとえば、親 ID が存在しない、リクエストされたディメンションや指標の組み合わせが無効であるなどの理由が考えられます。 問題を解決してから再試行してください。API クエリを正常に動作させるには、クエリに変更を加える必要があります。
401 invalidCredentials 認証トークンが無効であるか、期限切れであることを示します。 問題を解決してから再試行してください。新しい認証トークンを入手する必要があります。
403 insufficientPermissions クエリで指定されたエンティティに対する十分な権限がユーザーにないことを示します。 問題を解決してから再試行してください。指定したエンティティに対する操作を行うのに十分な権限を取得する必要があります。
403 dailyLimitExceeded ユーザーが、(プロジェクトあたり、またはビュー(旧プロファイル)あたりの)1 日の割り当てを超えたことを示します。 問題を解決してから再試行してください。1 日の割り当ての上限に達しました。API の制限と割り当てをご覧ください。
403 usageLimits.userRateLimitExceededUnreg Google API コンソールでアプリケーションの登録が必要で あることを示します。 問題を解決してから再試行してください。API 割り当て量を最大化するには、 API コンソールで登録を行う必要があります。
403 userRateLimitExceeded ユーザーのデータ処理上限を超えたことを示します。 データ処理の上限は、IP アドレスあたり 10 qps です。 Google API コンソールで設定されるデフォルト値は、IP アドレスあたり 1 qps です。 この上限は、Google API コンソール で最大 10 qps まで増やすことができ ます。 指数バックオフを使用して再試行してください。 リクエストの送信レートを抑える必要があります。
403 rateLimitExceeded グローバルまたはプロジェクト全体のレート制限を超えたことを示します。 指数バックオフを使用して再試行してください。リクエストの送信レートを抑える必要があります。
403 quotaExceeded Core Reporting API でビュー(旧プロファイル)あたりの同時リクエストが 10 に達したことを示します。 指数バックオフを使用して再試行してください。 このビュー(旧プロファイル)に対する処理中のリクエストが 少なくとも 1 件完了するまで待機する必要があります。
429 RESOURCE_EXHAUSTED AnalyticsDefaultGroupCLIENT_PROJECT-1d プロジェクトごとの 1 日あたりのリクエスト数 割り当て を使い切ったことを示します。 問題を解決してから再試行してください。1 日の割り当ての上限に 達しました。API の制限と割り当て をご覧ください。
429 RESOURCE_EXHAUSTED AnalyticsDefaultGroupCLIENT_PROJECT-100s プロジェクトごとの 100 秒あたりのリクエスト数 割り当て を使い切ったことを示します。 指数バックオフを使用して再試行してください。 リクエストの送信レートを抑える 必要があります。
429 RESOURCE_EXHAUSTED AnalyticsDefaultGroupUSER-100s プロジェクトごとの ユーザーあたりの 100 秒ごとのリクエスト数割り当て を使い切ったことを 示します。 指数バックオフを使用して再試行してください。 リクエストの送信レートを抑える 必要があります。
429 RESOURCE_EXHAUSTED DiscoveryGroupCLIENT_PROJECT-100s 100 秒あたりの ディスカバリー リクエスト数割り当て を使い切ったことを 示します。 ディスカバリー レスポンスは頻繁には変更されません。 ディスカバリー レスポンスをローカル キャッシュに入れるか 指数バックオフを使用して再試行してください。 リクエストの送信レートを 抑える必要があります。
500 internalServerError 予期しない内部サーバーエラーが発生しました。 このクエリを 2 回以上再試行しないでください。
503 backendError サーバーからエラーが返されました。 このクエリを 2 回以上再試行しないでください。

500 または 503 レスポンスの処理

500 エラーや 503 エラーは、負荷が高いときや、複雑な リクエストを大量に実行したときに発生することがあります。リクエストを大量に実行している場合は、データをリクエストする対象期間を短くすることや、指数バックオフを実装することをご検討ください。これらのエラーの頻度は、ビュー(旧プロファイル)やそれに関連付けられているレポートデータの量によって異なります。あるビュー(旧プロファイル)で 500 エラーや 503 エラーの原因となるクエリでも、別のビュー(旧プロファイル)ではエラーにならない場合もあります。

指数バックオフの実装

指数バックオフは、失敗したリクエストをクライアントが再試行する際、失敗するごとに次の再試行までの待ち時間を増やしていく処理です。これは、ネットワーク アプリケーションに使われる標準的なエラー処理方法です。Real Time Reporting API は、クライアントが失敗したリクエストを再試行する際に、指数バックオフが使われることを前提に設計されています。指数バックオフの使用は、「必須」であるということに加え、帯域利用の効率を高め、レスポンスを正しく取得するために必要なリクエストの数を減らし、同時実行環境におけるリクエストのスループットを最大化する効果もあります。

単純な指数バックオフを実装するフローを次に示します。

  1. API に対してリクエストを行います。
  2. 再試行可能なエラーコードを含むエラー レスポンスを受け取ります。
  3. 1 秒 + random_number_milliseconds 秒待機します。
  4. リクエストを再試行します。
  5. 再試行可能なエラーコードを含むエラー レスポンスを受け取ります。
  6. 2 秒 + random_number_milliseconds 秒待機します。
  7. リクエストを再試行します。
  8. 再試行可能なエラーコードを含むエラー レスポンスを受け取ります。
  9. 4 秒 + random_number_milliseconds 秒待機します。
  10. リクエストを再試行します。
  11. 再試行可能なエラーコードを含むエラー レスポンスを受け取ります。
  12. 8 秒 + random_number_milliseconds 秒待機します。
  13. リクエストを再試行します。
  14. 再試行可能なエラーコードを含むエラー レスポンスを受け取ります。
  15. 16 秒 + random_number_milliseconds 秒待機します。
  16. リクエストを再試行します。
  17. まだエラーが発生する場合は、停止してエラーを記録します。

上記のフローで、random_number_milliseconds は 1,000 ミリ秒以下のランダムなミリ秒数です。これは、一部の同時実装で起こる特定のロックエラーを回避するために必要です。 random_number_milliseconds は、待機するたびに再定義する必要があります。

: 待機時間は常に (2 ^ n) + random_number_milliseconds となります。ここで、n は、最初に 0 として定義されて、後は単調に増加する整数です。n は、反復(リクエスト)のたびに 1 ずつ増加します。

このアルゴリズムは、n が 5 になると終了するように設定されています。この上限値は、クライアントが無制限に再試行しないようにするためだけに設けられたもので、リクエストが「修復不可能なエラー」と見なされるまでに合計で約 32 秒間の遅延を生じます。

以下の Python コードは、makeRequest メソッドで 発生したエラーから回復するために上記で示したフローを 実装した例です。

import random
import time
from apiclient.errors import HttpError

def makeRequestWithExponentialBackoff(analytics):
  """Wrapper to request Google Analytics data with exponential backoff.

  The makeRequest method accepts the analytics service object, makes API
  requests and returns the response. If any error occurs, the makeRequest
  method is retried using exponential backoff.

  Args:
    analytics: The analytics service object

  Returns:
    The API response from the makeRequest method.
  """
  for n in range(0, 5):
    try:
      return makeRequest(analytics)

    except HttpError, error:
      if error.resp.reason in ['userRateLimitExceeded', 'quotaExceeded',
                               'internalServerError', 'backendError']:
        time.sleep((2 ** n) + random.random())
      else:
        break

  print "There has been an error, the request never succeeded."