Respuestas de error

Respuestas de error estándar

Si una solicitud a la API de informes en tiempo real es correcta, la API muestra un código de estado 200. Si se produce un error con una solicitud, la API muestra un código de estado HTTP, un estado y un motivo en la respuesta según el tipo de error. Además, el cuerpo de la respuesta contiene una descripción detallada de la causa del error. Este es un ejemplo de una respuesta de error:

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

Tabla de error

Código Motivo Descripción Acción recomendada
400 invalidParameter Indica que un parámetro de solicitud tiene un valor no válido. Los campos locationType y location de la respuesta de error proporcionan información sobre qué valor no es válido. No vuelvas a intentar la operación sin solucionar el problema. Debes proporcionar un valor válido para el parámetro especificado en la respuesta de error.
400 badRequest Indica que la consulta no es válida. P.ej., falta el ID principal o la combinación de dimensiones o métricas solicitadas no es válida. No vuelvas a intentar la operación sin solucionar el problema. Debe realizar cambios en la consulta de la API para que funcione.
401 invalidCredentials Indica que el token de autenticación no es válido o venció. No vuelvas a intentar la operación sin solucionar el problema. Debes obtener un nuevo token de autenticación.
403 insufficientPermissions Indica que el usuario no tiene permisos suficientes para la entidad especificada en la consulta. No vuelvas a intentar la operación sin solucionar el problema. Debes obtener permisos suficientes para realizar la operación en la entidad especificada.
403 dailyLimitExceeded Indica que el usuario excedió la cuota diaria (ya sea por proyecto o por vista (perfil)). No vuelvas a intentar la operación sin solucionar el problema. Usaste tu cuota diaria. Consulta Límites y cuotas de API.
403 userRateLimitExceeded Indica que se superó el límite de consultas cada 100 segundos por usuario. El valor predeterminado establecido en la Consola de API de Google es de 100 consultas por 100 segundos por usuario. Puedes aumentar este límite en la Consola de API de Google a un máximo de 1,000. Vuelve a intentarlo con la retirada exponencial. Debes disminuir la velocidad a la que envías las solicitudes.
403 rateLimitExceeded Indica que se excedieron los límites de frecuencia de consultas cada 100 segundos del proyecto. Vuelve a intentarlo con la retirada exponencial. Debes disminuir la velocidad a la que envías las solicitudes.
403 quotaExceeded Indica que se alcanzaron las 10 solicitudes simultáneas por vista (perfil) en la API de Core Reporting. Vuelve a intentarlo con la retirada exponencial. Debes esperar a que se complete al menos una solicitud en curso para esta vista (perfil).
500 internalServerError Se produjo un error interno inesperado en el servidor. No vuelvas a intentar esta consulta más de una vez.
503 backendError El servidor mostró un error. No vuelvas a intentar esta consulta más de una vez.

Cómo manejar respuestas 500 o 503

Un error 500 o 503 puede generarse durante cargas pesadas o solicitudes más complejas. Para solicitudes más grandes, considera solicitar datos durante un período más corto. Además, considera implementar la retirada exponencial. La frecuencia de estos errores puede depender de la vista (perfil) y de la cantidad de datos de informes asociados con esa vista. Una consulta que provoca un error 500 o 503 para una vista (perfil) no necesariamente generará un error para la misma consulta con una vista diferente (perfil).

Implementar retirada exponencial

La retirada exponencial es el proceso de un cliente que vuelve a intentar una solicitud con errores de forma periódica durante un período cada vez mayor. Es una estrategia estándar de manejo de errores para aplicaciones de red. La API de informes en tiempo real está diseñada con la expectativa de que los clientes que elijan reintentar las solicitudes fallidas lo hagan mediante la retirada exponencial. Además de ser obligatorio, el uso de la retirada exponencial aumenta la eficiencia del uso del ancho de banda, reduce la cantidad de solicitudes necesarias para obtener una respuesta exitosa y maximiza la capacidad de procesamiento de las solicitudes en entornos simultáneos.

El flujo para implementar una retirada exponencial simple es el siguiente.

  1. Realiza una solicitud a la API
  2. Recibir una respuesta de error que tiene un código de error que se puede reintentar
  3. Esperar 1 s + random_number_milliseconds segundos
  4. Volver a intentar solicitud
  5. Recibir una respuesta de error que tiene un código de error que se puede reintentar
  6. Espera 2 s + random_number_milliseconds segundos
  7. Volver a intentar solicitud
  8. Recibir una respuesta de error que tiene un código de error que se puede reintentar
  9. Espera 4 s + random_number_milliseconds segundos
  10. Volver a intentar solicitud
  11. Recibir una respuesta de error que tiene un código de error que se puede reintentar
  12. Esperar 8 s + random_number_milliseconds segundos
  13. Volver a intentar solicitud
  14. Recibir una respuesta de error que tiene un código de error que se puede reintentar
  15. Espera 16 s + random_number_milliseconds segundos
  16. Volver a intentar solicitud
  17. Si aún recibes un error, detente y registra el error.

En el flujo anterior, random_number_milliseconds es un número aleatorio de milisegundos menor o igual que 1,000. Esto es necesario para evitar ciertos errores de bloqueo en algunas implementaciones simultáneas. random_number_milliseconds debe volver a definirse después de cada espera.

Nota: La espera siempre es (2 ^ n) + random_number_milliseconds, en la que n es un número entero que aumenta de forma monótona, inicialmente definido como 0. n aumenta de 1 a cada iteración (cada solicitud).

El algoritmo está configurado para terminar cuando n sea 5. Este límite se establece solo para evitar que los clientes vuelvan a intentarlo de forma infinita y genera un retraso total de aproximadamente 32 segundos antes de que se considere que una solicitud es un error irrecuperable.

El siguiente código de Python es una implementación del flujo anterior para recuperarse de los errores que ocurren en un método llamado 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."