Respuestas de error

Respuestas de error estándar

Si una solicitud de la API de informes se realiza correctamente, la API devuelve un código de estado HTTP 200, junto con los datos solicitados en el cuerpo de la respuesta.

Si se produce un error con una solicitud, la API devuelve un código de estado HTTP 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 lo que ha provocado el error. A continuación se presenta un ejemplo de una respuesta de error:

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

Nota: La descripción podría cambiar en cualquier momento, por lo que las aplicaciones no deben depender del texto de la descripción real.

En la lista siguiente se muestran los posibles códigos de error, los motivos, las descripciones correspondientes y la acción recomendada.

Código Motivo Descripción Acción recomendada
400 invalidParameter Indica que un parámetro de solicitud tiene un valor no válido. En los campos locationType y location de la respuesta de error se proporciona información sobre el motivo por el que no es válido el valor. No vuelvas a intentar la acción sin antes corregir el problema. Debes proporcionar un valor válido del parámetro especificado en la respuesta de error.
400 badRequest Indica que la consulta no es válida. Por ejemplo, falta el ID principal o la combinación de dimensiones o métricas solicitadas no es válida. No vuelvas a intentar la acción sin antes corregir el problema. Debes 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 ha caducado. No vuelvas a intentar la acción sin antes corregir el problema. Debes obtener un nuevo token de autenticación.
403 insufficientPermissions Indica que el usuario no tiene suficientes permisos para la entidad especificada en la consulta. No vuelvas a intentar la acción sin antes corregir el problema. Debes obtener suficientes permisos para realizar la operación en la entidad especificada.
403 dailyLimitExceeded Indica que el usuario ha superado la cuota diaria (por proyecto o por vista [perfil]). No vuelvas a intentar la acción sin antes corregir el problema. Has agotado tu cuota diaria. Consulta Límites y cuotas de la API.
403 usageLimits.userRateLimitExceededUnreg Indica que la aplicación debe registrarse en la consola de la API de Google. No vuelvas a intentar la acción sin antes corregir el problema. Debes registrar la aplicación en la consola de la API para recuperar la cuota.
403 userRateLimitExceeded Indica que se ha superado el límite de tasa de usuario. El límite de velocidad máximo es de diez consultas por segundo por dirección IP. El valor predeterminado definido en la consola de la API de Google es de una consulta por segundo por dirección IP. Puedes aumentar este límite en la consola de la API de Google hasta un máximo de diez consultas por segundo. Vuelve a intentarlo con un retardo exponencial. Debes reducir la velocidad a la que envías las solicitudes.
403 rateLimitExceeded Indica que se han superado los límites de velocidad globales o totales del proyecto. Vuelve a intentarlo con un retardo exponencial. Debes reducir la velocidad a la que envías las solicitudes.
403 quotaExceeded Indica que se han alcanzado las diez solicitudes simultáneas por vista (perfil) en la API de informes centrales. Vuelve a intentarlo con un retardo exponencial. Debes esperar a que se complete al menos una consulta en curso correspondiente a esta vista (perfil).
429 RESOURCE_EXHAUSTED AnalyticsDefaultGroupCLIENT_PROJECT-1d Indica que se ha agotado la cuota de solicitudes diarias por proyecto. No vuelvas a intentar la acción sin antes corregir el problema. Has agotado tu cuota diaria. Consulta Límites y cuotas de la API.
429 RESOURCE_EXHAUSTED AnalyticsDefaultGroupCLIENT_PROJECT-100s Indica que se ha agotado la cuota de solicitudes por cada 100 segundos por usuario y proyecto. Vuelve a intentarlo con un retardo exponencial. Debes reducir la velocidad a la que envías las solicitudes.
429 RESOURCE_EXHAUSTED AnalyticsDefaultGroupUSER-100s Indica que se ha agotado la cuota de solicitudes por cada 100 segundos por usuario y proyecto. Vuelve a intentarlo con un retardo exponencial. Debes reducir la velocidad a la que envías las solicitudes.
429 RESOURCE_EXHAUSTED DiscoveryGroupCLIENT_PROJECT-100s Indica que se ha agotado la cuota de solicitudes de detección por cada 100 segundos. La respuesta de detección no cambia muy a menudo; guarda localmente la respuesta de detección en la caché o intenta utilizar un retardo exponencial de nuevo. Debes reducir la velocidad a la que envías las solicitudes.
500 internalServerError Se ha producido un error interno inesperado del servidor. No vuelvas a intentar esta consulta más de una vez.
503 backendError El servidor ha devuelto un error. No vuelvas a intentar esta consulta más de una vez.

Gestionar respuestas 500 o 503

Un error 500 o 503 se puede producir durante una carga intensa o en solicitudes más complejas y grandes. En el caso de las solicitudes más grandes, considera la posibilidad de solicitar datos durante un periodo de tiempo más breve. Asimismo, puedes implementar un retardo exponencial. La frecuencia de estos errores puede depender de la vista (perfil) y la cantidad de datos asociados a esa vista. Una consulta que provoque un error 500 o 503 para una vista (perfil) no necesariamente provocará un error para la misma consulta con otra vista (perfil).

Implementación de un retardo exponencial

El retardo exponencial es el proceso de un cliente que reintenta periódicamente una solicitud con error durante un periodo que se va incrementando. Se trata de una estrategia de gestión de errores estándar para las aplicaciones de red. La API de informes se ha diseñado con la expectativa de que los clientes que deciden reintentar las solicitudes con error lo hagan con un retardo exponencial. Además de ser "obligatorio", el uso del retardo exponencial aumenta la eficiencia del uso del ancho de banda, reduce el número de solicitudes necesarias para obtener una respuesta correcta y maximiza el rendimiento de las solicitudes en entornos simultáneos.

A continuación se indica el flujo para implementar el retardo exponencial simple.

  1. Realizar una solicitud a la API
  2. Recibir una respuesta de error que tenga un código de error que se pueda recuperar
  3. Esperar un segundo más número_aleatorio_de_milisegundos segundos
  4. Reintentar la solicitud
  5. Recibir una respuesta de error que tenga un código de error que se pueda recuperar
  6. Esperar dos segundos más número_aleatorio_de_milisegundos segundos
  7. Reintentar la solicitud
  8. Recibir una respuesta de error que tenga un código de error que se pueda recuperar
  9. Esperar cuatro segundos más número_aleatorio_de_milisegundos segundos
  10. Reintentar la solicitud
  11. Recibir una respuesta de error que tenga un código de error que se pueda recuperar
  12. Esperar ocho segundos más número_aleatorio_de_milisegundos segundos
  13. Reintentar la solicitud
  14. Recibir una respuesta de error que tenga un código de error que se pueda recuperar
  15. Esperar dieciséis segundos más número_aleatorio_de_milisegundos segundos
  16. Reintentar la solicitud
  17. Si se sigue obteniendo un error, detener la solicitud y registrar el error.

En el flujo anterior, número_aleatorio_de_milisegundos es un número menor o igual que 1000. Esto es necesario para evitar determinados errores de bloqueo en algunas implementaciones simultáneas. El valor de número_aleatorio_de_milisegundos se debe redefinir después de cada espera.

Nota: La espera siempre es (2 ^ n) + número_aleatorio_de_milisegundos, donde n es un entero que se incrementa monotónicamente definido inicialmente como 0. El valor de n se incrementa en 1 en cada iteración (cada solicitud).

El algoritmo está configurado para terminar cuando n es 5. Este límite solo se aplica para impedir que los clientes reintenten la operación indefinidamente. El resultado es un retardo total de 32 segundos antes de que una solicitud se considere "un error irrecuperable".

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