Tipos de errores

Clasificamos los errores en las siguientes categorías generales:

  • Autenticación
  • Errores que se pueden volver a intentar
  • Validación
  • Relacionados con la sincronización

Si bien estas categorías no abarcan todos los errores posibles y algunos pueden pertenecer a más de una categoría, pueden servir como punto de partida para estructurar el manejo de errores de tu app. Consulta los siguientes recursos para obtener más detalles sobre errores específicos:

  • En Errores comunes, se proporcionan más detalles sobre un error en particular.
  • google.rpc.Status proporciona detalles sobre el modelo de error lógico que usa la API.
  • En Códigos de error canónicos, se proporciona una lista y una explicación de los códigos de error canónicos definidos por gRPC y HTTP en el contexto de la API de Google Ads.

Errores de autenticación

La autenticación se refiere a si un usuario le otorgó permiso a tu app para acceder a Google Ads en su nombre. La autenticación se administra a través de las credenciales generadas por el flujo de OAuth2.

La razón más común por la que se produce un error de autenticación debido a factores que escapan a tu control es que el usuario autenticado revocó el permiso que le otorgó a tu app para actuar en su nombre. Por ejemplo, si tu app administra cuentas de Google Ads independientes para clientes individuales y se autentica por separado como cada cliente cuando administra su cuenta, un cliente podría revocar el acceso de tu app en cualquier momento. Según el momento en que se revocó tu acceso, la API puede devolver directamente un error AuthenticationError.OAUTH_TOKEN_REVOKED o los objetos de credenciales integrados en las bibliotecas cliente pueden arrojar una excepción de token revocado. En cualquier caso, si tu app tiene una IU para tus clientes, podría pedirles que vuelvan a iniciar el flujo de OAuth2 para restablecer el permiso de tu app para actuar en su nombre.

En relación con esto, si tu proyecto de Google Cloud solo tiene el nivel de acceso de prueba y trata de realizar solicitudes a una cuenta de producción (que no sea de prueba), la API devuelve un AuthorizationError cuyo valor de enumeración depende de la versión de la API:

Errores que se pueden volver a intentar

Algunos errores, como TRANSIENT_ERROR o INTERNAL_ERROR, pueden indicar un problema temporal que se puede resolver si vuelves a intentar la solicitud después de una breve pausa.

En el caso de las solicitudes iniciadas por el usuario, una estrategia es indicar de inmediato un error en la IU y darle al usuario la opción de activar un reintento. Como alternativa, tu app podría volver a intentar la solicitud de forma automática y mostrar el error en la IU solo después de alcanzar una cantidad máxima de reintentos o un tiempo de espera total del usuario.

En el caso de las solicitudes iniciadas en el backend, tu app debería volver a intentar la solicitud automáticamente hasta una cantidad máxima de reintentos.

Cuando vuelvas a intentar las solicitudes, usa una política de retirada exponencial con una fluctuación aleatoria. Por ejemplo, si primero pausas 5 segundos antes del primer reintento, podrías pausar 10 segundos después del segundo y 20 segundos después del tercer reintento, lo que agrega un pequeño retraso aleatorio a cada intervalo para evitar picos de reintentos sincronizados. La retirada exponencial ayuda a garantizar que no llames a la API de forma demasiado agresiva. Si un error persiste después de agotar los reintentos, registra el request-id de la respuesta para solucionar problemas.

Errores de validación

Los errores de validación indican que una entrada para una operación no era aceptable. Algunos ejemplos son PolicyViolationError, DateError, DateRangeError, StringLengthError y UrlFieldError.

Los errores de validación ocurren con mayor frecuencia en las solicitudes iniciadas por el usuario, en las que un usuario ingresó una entrada no válida. En estos casos, debes proporcionar un mensaje de error adecuado al usuario según el error de la API específico que recibiste. También puedes validar la entrada del usuario para detectar errores comunes antes de realizar una llamada a la API, lo que hará que tu app sea más responsiva y que el uso de la API sea más eficiente. En el caso de las solicitudes del backend, tu app podría agregar la operación fallida a una cola para que la revise un operador humano.

Muchas apps de Google Ads mantienen una base de datos local para almacenar sus objetos de Google Ads. Un desafío de este enfoque es que la base de datos local puede desincronizarse con los objetos reales de Google Ads. Por ejemplo, un usuario podría borrar un grupo de anuncios directamente en Google Ads, pero la app y la base de datos local no se enterarían del cambio y seguirían emitiendo llamadas a la API como si el grupo de anuncios existiera. Estos problemas de sincronización pueden manifestarse como una variedad de errores, como DUPLICATE_CAMPAIGN_NAME, DUPLICATE_ADGROUP_NAME, AD_NOT_UNDER_ADGROUP, CANNOT_OPERATE_ON_REMOVED_ADGROUPAD y muchos otros.

En el caso de las solicitudes iniciadas por el usuario, una estrategia es alertar al usuario sobre un posible problema de sincronización, iniciar de inmediato un trabajo que recupere la clase relevante de objetos de Google Ads y actualice la base de datos local, y, luego, solicitar al usuario que actualice la IU.

En el caso de las solicitudes de backend, algunos errores proporcionan suficiente información para que tu app corrija de forma automática y progresiva tu base de datos local. Por ejemplo, CANNOT_OPERATE_ON_REMOVED_ADGROUPAD debería hacer que tu app marque ese anuncio como quitado en tu base de datos local. Los errores que no puedas controlar de esta manera podrían hacer que tu app inicie un trabajo de sincronización más completo o que se agregue a una cola para que un operador humano la revise.

Siguiente
Información sobre los errores de la API