Google Analytics

Error Responses

  1. Standard Error Responses
  2. Implementing Exponential Backoff

Standard Error Responses

If a Core Reporting API request is successful, the API returns a 200 HTTP status code along with the requested data in the body of the response.

If an error occurs with a request, the API returns an HTTP status code and reason in the response based on the type of error. Additionally, the body of the response contains a detailed description of what caused the error. Here's an example of an error response:

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]"
 }
}

Note: The description could change at any time so applications should not depend on the actual description text.

The following list shows the possible error codes, reasons, corresponding descriptions, and recommended action.

Code Reason Description Recommended Action
400 invalidParameter Indicates that a request parameter has an invalid value. The locationType and location fields in the error response provide information as to which value was invalid. Do not retry without fixing the problem. You need to provide a valid value for the parameter specified in the error response.
400 badRequest Indicates that the query was invalid. E.g., parent ID was missing or the combination of dimensions or metrics requested was not valid. Do not retry without fixing the problem. You need to make changes to the API query in order for it to work.
401 invalidCredentials Indicates that the auth token is invalid or has expired. Do not retry without fixing the problem. You need to get a new auth token.
403 insufficientPermissions Indicates that the user does not have sufficient permissions for the entity specified in the query. Do not retry without fixing the problem. You need to get sufficient permissions to perform the operation on the specified entity.
403 dailyLimitExceeded Indicates that user has exceeded the daily quota (either per project or per profile). Do not retry without fixing the problem. You have used up your daily quota. See API Limits and Quotas.
403 usageLimits.userRateLimitExceededUnreg Indicates that the application needs to be registered in the Google Developers Console. Do not retry without fixing the problem. You need to register in Developers Console to get the full API quota.
403 userRateLimitExceeded Indicates that the user rate limit has been exceeded. The maximum rate limit is 10 qps per IP address. The default value set in Google Developers Console is 1 qps per IP address. You can increase this limit in the Google Developers Console to a maximum of 10 qps. Retry using exponential back-off. You need to slow down the rate at which you are sending the requests.
403 quotaExceeded Indicates that the 10 concurrent requests per profile in the Core Reporting API has been reached. Retry using exponential back-off. You need to wait for at least one in-progress request for this profile to complete.
503 backendError Server returned an error. Do not retry this query more than once.

Implementing Exponential Backoff

Exponential backoff is the process of a client periodically retrying a failed request over an increasing amount of time. It is a standard error handling strategy for network applications. The Core Reporting API is designed with the expectation that clients which choose to retry failed requests do so using exponential backoff. Besides being "required", using exponential backoff increases the efficiency of bandwidth usage, reduces the number of requests required to get a successful response, and maximizes the throughput of requests in concurrent environments.

The flow for implementing simple exponential backoff is as follows.

  1. Make a request to the API
  2. Receive an error response that has a retry-able error code
  3. Wait 1s + random_number_milliseconds seconds
  4. Retry request
  5. Receive an error response that has a retry-able error code
  6. Wait 2s + random_number_milliseconds seconds
  7. Retry request
  8. Receive an error response that has a retry-able error code
  9. Wait 4s + random_number_milliseconds seconds
  10. Retry request
  11. Receive an error response that has a retry-able error code
  12. Wait 8s + random_number_milliseconds seconds
  13. Retry request
  14. Receive an error response that has a retry-able error code
  15. Wait 16s + random_number_milliseconds seconds
  16. Retry request
  17. If you still get an error, stop and log the error.

In the above flow, random_number_milliseconds is a random number of milliseconds less than or equal to 1000. This is necessary to avoid certain lock errors in some concurrent implementations. random_number_milliseconds must be redefined after each wait.

Note: the wait is always (2 ^ n) + random_number_milliseconds, where n is a monotonically increasing integer initially defined as 0. n is incremented by 1 for each iteration (each request).

The algorithm is set to terminate when n is 5. This ceiling is in place only to stop clients from retrying infinitely, and results in a total delay of around 32 seconds before a request is deemed "an unrecoverable error".

The following Python code is an implementation of the above flow for recovering from errors that occur in a method called 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']:
        time.sleep((2 ** n) + random.random())

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

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.