Respostas de erro

Respostas de erro padrão

Se uma solicitação da Reporting API de funis multicanal for bem-sucedida, a API retornará um código de status 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": {
  "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]"
 }
}

Tabela de erros

Código Motivo Descrição Ação recomendada
400 invalidParameter Indica que um parâmetro de solicitação tem um valor inválido. Os campos locationType e location na resposta de erro fornecem informações sobre qual valor era inválido. Não tente novamente sem resolver o problema. Você precisa fornecer um valor válido para o parâmetro especificado na resposta de erro.
400 badRequest Indica que a consulta era inválida. Por exemplo, o ID pai estava ausente ou a combinação solicitada de dimensões ou métricas não era válida. Não tente novamente sem corrigir o problema. Você precisa fazer alterações na consulta da API para que ela funcione.
401 invalidCredentials Indica que o token de autenticação é inválido ou expirou. Não tente novamente sem corrigir o problema. Você precisa receber um novo token de autenticação.
403 insufficientPermissions Indica que o usuário não tem permissões suficientes para a entidade especificada na consulta. Não tente novamente sem corrigir o problema. Você precisa receber permissões suficientes para executar a operação na entidade especificada.
403 dailyLimitExceeded Indica que o usuário ultrapassou a cota diária, por projeto ou vista (perfil). Não tente novamente sem corrigir o problema. Você esgotou sua cota diária. Consulte Limites e cotas da API.
403 userRateLimitExceeded Indica que o limite de consultas a cada 100 segundos por usuário foi excedido. O valor padrão definido no Console de APIs do Google é de 100 consultas a cada 100 segundos por usuário. Você pode aumentar esse limite no Console de APIs do Google para até 1.000. Tente novamente usando a espera exponencial (em inglês). Você precisa desacelerar a taxa de envio das solicitações.
403 rateLimitExceeded Indica que os limites da taxa de consultas a cada 100 segundos do projeto foram excedidos. Tente novamente usando a espera exponencial (em inglês). Você precisa desacelerar a taxa de envio das solicitações.
403 quotaExceeded Indica que o limite de 10 solicitações simultâneas por vista (perfil) na Core Reporting API foi atingido. Tente novamente usando a espera exponencial (em inglês). Você precisa aguardar pelo menos uma solicitação em andamento para que esta vista (perfil) seja concluída.
500 internalServerError Ocorreu um erro interno do servidor inesperado. Não repita essa consulta mais de uma vez.
503 backendError O servidor retornou um erro. Não repita essa consulta mais de uma vez.

Como solucionar respostas 500 ou 503

Pode ocorrer um erro 500 ou 503 durante uma sobrecarga ou para solicitações maiores e mais complexas. Para solicitações maiores, avalie a possibilidade de solicitar dados de um período menor. Considere também implementar a espera exponencial. A frequência desses erros pode depender da vista (perfil) e da quantidade de dados de relatório associados a ela. Uma consulta que cause um erro 500 ou 503 a uma vista (perfil) não necessariamente vai gerar um erro para a mesma consulta com outra vista (perfil).

Como implementar espera 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 de funis multicanal 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. Aguarde 1s e 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. Aguarde 2s e 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. Aguarde 8s + 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 16 s + 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 inferior 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."