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 está enviando 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 está enviando 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 em cache localmente ou tente novamente 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.
- Fazer uma solicitação para a API
- Receber uma resposta de erro que tem um código de erro passível de repetição
- Esperar 1 s +
random_number_milliseconds
segundos - Repetir a solicitação
- Receber uma resposta de erro que tem um código de erro passível de repetição
- Esperar 2 s +
random_number_milliseconds
segundos - Repetir a solicitação
- Receber uma resposta de erro que tem um código de erro passível de repetição
- Aguarde 4 s +
random_number_milliseconds
segundos - Repetir a solicitação
- Receber uma resposta de erro que tem um código de erro passível de repetição
- Aguarde 8 s +
random_number_milliseconds
segundos - Repetir a solicitação
- Receber uma resposta de erro que tem um código de erro passível de repetição
- Aguarde 16s +
random_number_milliseconds
segundos - Repetir a solicitação
- 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 (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."