Respostas de erro

Respostas de erro padrão

Se uma solicitação da Reporting API for bem-sucedida, a API retornará 200. Se ocorrer um erro com uma solicitação, a API retornará um código de status HTTP, o status e o motivo na resposta com base no tipo de erro. Além disso, o corpo da resposta conterá uma descrição detalhada sobre o que causou o erro. Veja um exemplo de uma resposta de erro:

{
 "error": {
  "code": 403,
  "message": "User does not have sufficient permissions for this profile.",
  "status": "PERMISSION_DENIED"
 }
}

Tabela de erros

Código Status Descrição Ação recomendada
400 INVALID_ARGUMENT A solicitação é inválida. Um argumento exigido pode estar ausente, ter excedido os limites ou conter um valor inválido. Veja os detalhes na mensagem de erro. O erro ocorrerá novamente se o cliente fizer uma nova tentativa.
401 UNAUTHENTICATED O cliente não está devidamente autenticado. Não tente novamente sem corrigir o problema. Você precisa receber um novo token de autenticação.
403 PERMISSION_DENIED Indica a solicitação de dados à qual o usuário não tem acesso. Não tente novamente sem corrigir o problema. Você precisa receber permissões suficientes para executar a operação na entidade especificada.
429 RESOURCE_EXHAUSTED AnalyticsDefaultGroupCLIENT_PROJECT-1d Indica que a cota de solicitações por dia e por projeto foi esgotada. Não tente novamente sem corrigir o problema. Você esgotou sua cota diária.
429 RESOURCE_EXHAUSTED AnalyticsDefaultGroupCLIENT_PROJECT-100s Indica que a cota de solicitações a cada 100 segundos por projeto foi esgotada. Tente novamente usando a espera exponencial. Você precisa diminuir a taxa em que envia as solicitações.
429 RESOURCE_EXHAUSTED AnalyticsDefaultGroupUSER-100s Indica que a cota de solicitações a cada 100 segundos por usuário e por projeto foi esgotada. Tente novamente usando a espera exponencial. Você precisa diminuir a taxa em que envia as solicitações.
429 RESOURCE_EXHAUSTED DiscoveryGroupCLIENT_PROJECT-100s Indica que a cota de solicitações de descoberta a cada 100 segundos foi esgotada. Como a resposta de descoberta não muda com frequência. Armazene a resposta de descoberta em cache localmente ou tente de novo usando a espera exponencial. Você precisa diminuir a taxa de envio das solicitações.
500 INTERNAL Ocorreu um erro interno do servidor inesperado. Não repita essa consulta mais de uma vez.
503 BACKEND_ERROR O servidor retornou um erro. Não repita essa consulta mais de uma vez.
503 UNAVAILABLE Não foi possível processar a solicitação. Provavelmente, essa é uma condição transitória e poderá ser corrigida com uma nova tentativa de uso do backoff exponencial.

Como implementar backoff exponencial

Backoff exponencial é o processo em que um cliente repete periodicamente uma solicitação com falha por um período cada vez maior. É uma estratégia de gerenciamento de erros padrão para aplicativos de rede. A Reporting API foi desenvolvida com a expectativa de que os clientes que optam por repetir solicitações com falha façam isso usando backoff exponencial. Além de ser "necessário", o uso de backoff exponencial aumenta a eficiência do uso de largura de banda, reduz o número de solicitações necessárias para receber uma resposta bem-sucedida e maximiza o rendimento de solicitações em ambientes simultâneos.

Veja a seguir o fluxo de implementação de backoff exponencial simples.

  1. Fazer uma solicitação para a API
  2. Receber uma resposta de erro que tem um código de erro passível de repetição
  3. Esperar 1 s + random_number_milliseconds segundos
  4. Repetir a solicitação
  5. Receber uma resposta de erro que tem um código de erro passível de repetição
  6. Esperar 2s + random_number_milliseconds segundos
  7. Repetir a solicitação
  8. Receber uma resposta de erro que tem um código de erro passível de repetição
  9. Aguarde 4s + random_number_milliseconds segundos
  10. Repetir a solicitação
  11. Receber uma resposta de erro que tem um código de erro passível de repetição
  12. Esperar 8 s + random_number_milliseconds segundos
  13. Repetir a solicitação
  14. Receber uma resposta de erro que tem um código de erro passível de repetição
  15. Esperar 16s + random_number_milliseconds segundos
  16. Repetir a solicitação
  17. Se você continuar recebendo um erro, pare e registre-o.

No fluxo acima, random_number_milliseconds é um número aleatório de milissegundos menor ou igual a 1.000. Ele é necessário para evitar determinados erros de bloqueio em algumas implementações simultâneas. É preciso redefinir o random_number_milliseconds após cada espera.

Observação: o período de espera sempre é (2 ^ n) + random_number_milliseconds, em que n é um número inteiro monotonicamente crescente, definido inicialmente como 0. O valor n é incrementado em 1 a cada iteração (a cada solicitação).

O algoritmo é definido para terminar quando n é 5. Esse limite entra em vigor somente para impedir que os clientes façam novas tentativas infinitamente e resulta em um atraso total de cerca de 32 segundos antes de uma solicitação ser considerada "um erro irrecuperável".

O código Python a seguir é uma implementação do fluxo acima para a recuperação de erros que ocorrem em um método chamado 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."