Información sobre los errores de la API

En esta guía, se explica cómo la API de Google Ads controla y comunica los errores. Comprender la estructura y el significado de los errores de la API es fundamental para compilar aplicaciones sólidas que puedan controlar los problemas con elegancia, desde entradas no válidas hasta la falta de disponibilidad temporal del servicio.

La API de Google Ads sigue el modelo de error estándar de la API de Google, que se basa en los códigos de estado de gRPC. Cada respuesta de la API que genera un error incluye un objeto Status que contiene lo siguiente:

• Un código de error numérico
• Un mensaje de error
• Detalles adicionales sobre el error (opcional)

Códigos de error canónicos

La API de Google Ads usa un conjunto de códigos de error canónicos definidos por gRPC y HTTP. Estos códigos proporcionan una indicación de alto nivel del tipo de error. Siempre debes verificar este código numérico primero para comprender la naturaleza fundamental del problema.

En la siguiente tabla, se resumen los códigos más comunes que puedes encontrar cuando usas la API de Google Ads:

Para obtener más detalles sobre estos códigos, consulta la Guía de diseño de API: Códigos de error.

Comprende los detalles del error

Además del código de nivel superior, la API de Google Ads proporciona información más específica sobre los errores en el campo details del objeto Status. Este campo suele contener un GoogleAdsFailure proto, que incluye una lista de objetos individuales GoogleAdsError.

Cada objeto GoogleAdsFailure contiene lo siguiente:

• errors: Una lista de objetos GoogleAdsError, cada uno de los cuales detalla un error específico que se produjo.
• request_id: Un ID único para la solicitud, útil para la depuración y la asistencia.

Cada objeto GoogleAdsError proporciona lo siguiente:

• errorCode: Un código de error más detallado, específico de la API de Google Ads, como AuthenticationError.NOT_ADS_USER.
• message: Una descripción legible del error específico.
• trigger: El valor que causó el error, si corresponde.
• location: Describe dónde se produjo el error en la solicitud, incluidas las rutas de acceso a los campos.
• details: Detalles adicionales sobre el error, como los motivos de error no publicados.

Ejemplo de detalles del error

Cuando recibas un error, tu biblioteca cliente te permitirá acceder a estos detalles. Por ejemplo, un INVALID_ARGUMENT (código 3) podría tener detalles de GoogleAdsFailure como este:

{
  "code": 3,
  "message": "The request was invalid.",
  "details": [
    {
      "@type": "type.googleapis.com/google.ads.googleads.v24.errors.GoogleAdsFailure",
      "errors": [
        {
          "errorCode": {
            "fieldError": "REQUIRED"
          },
          "message": "The required field was not present.",
          "location": {
            "fieldPathElements": [
              { "fieldName": "operations" },
              { "fieldName": "create" },
              { "fieldName": "name" }
            ]
          }
        },
        {
          "errorCode": {
            "stringLengthError": "TOO_SHORT"
          },
          "message": "The provided string is too short.",
          "trigger": {
            "stringValue": ""
          },
          "location": {
            "fieldPathElements": [
              { "fieldName": "operations" },
              { "fieldName": "create" },
              { "fieldName": "description" }
            ]
          }
        }
      ]
    }
  ]
}

En este ejemplo, a pesar del INVALID_ARGUMENT de nivel superior, los GoogleAdsFailure detalles te indican que los name y description campos causaron el problema y por qué (REQUIRED y TOO_SHORT, respectivamente).

Ubica los detalles del error

La forma en que accedes a los detalles del error depende de si usas llamadas a la API estándar, fallas parciales o transmisión.

Llamadas a la API estándar y de transmisión

Cuando falla una llamada a la API sin usar una falla parcial, incluidas las llamadas de transmisión, el GoogleAdsFailure objeto se muestra como parte de los metadatos finales en los encabezados de respuesta de gRPC. Si usas REST para las llamadas estándar, GoogleAdsFailure se muestra en la respuesta HTTP. Las bibliotecas cliente por lo general muestran esto como una excepción con un atributo GoogleAdsFailure.

Falla parcial

Si usas falla parcial, los errores de las operaciones fallidas se muestran en el campo partial_failure_error de la respuesta, no en los encabezados de respuesta. En este caso, el GoogleAdsFailure está incorporado en un objeto google.rpc.Status en la respuesta.

Trabajos por lotes

Para el procesamiento por lotes, los errores de las operaciones individuales se pueden encontrar recuperando los resultados del trabajo por lotes una vez que se completa el trabajo. Cada resultado de la operación incluirá un campo status que contiene detalles del error si la operación falló.

ID de solicitud

El request-id es una cadena única que identifica tu solicitud a la API y es esencial para solucionar problemas.

Puedes encontrar el request-id en varios lugares:

• GoogleAdsFailure: Si falla una llamada a la API y GoogleAdsFailure se muestra, contendrá un request_id.
• Metadatos finales: Para las solicitudes exitosas y fallidas, request-id está disponible en los metadatos finales de la respuesta de gRPC.
• Encabezados de respuesta: Para las solicitudes exitosas y fallidas, request-id está también disponible en los encabezados de respuesta de gRPC y respuesta HTTP, con la excepción de las solicitudes de transmisión exitosas.
• SearchGoogleAdsStreamResponse: Para las solicitudes de transmisión, cada SearchGoogleAdsStreamResponse mensaje contiene un campo request_id.

Cuando registres errores o te comuniques con el equipo de asistencia, asegúrate de incluir el request-id para ayudar a diagnosticar los problemas.

Prácticas recomendadas para el manejo de errores

Para compilar aplicaciones resilientes, implementa las siguientes prácticas recomendadas:

1. Inspecciona los detalles del error: Siempre analiza el campo details del Status objeto y busca específicamente GoogleAdsFailure. Los campos detallados errorCode, message, y location dentro de GoogleAdsError proporcionan la información más útil para la depuración y los comentarios de los usuarios.

2. Distingue los errores del cliente de los errores del servidor:

   • Errores del cliente: Códigos como INVALID_ARGUMENT, NOT_FOUND, PERMISSION_DENIED, FAILED_PRECONDITION, UNAUTHENTICATED. Estos requieren cambios en la solicitud o en el estado o las credenciales de tu aplicación. No vuelvas a intentar la solicitud sin solucionar el problema.
   • Errores del servidor: Códigos como UNAVAILABLE, INTERNAL, DEADLINE_EXCEEDED, UNKNOWN. Estos sugieren un problema temporal con el servicio de la API.

3. Implementa una estrategia de reintento:

   • Cuándo volver a intentarlo: Vuelve a intentarlo solo para errores transitorios del servidor, como UNAVAILABLE, DEADLINE_EXCEEDED, INTERNAL, UNKNOWN y ABORTED.
   • Retirada exponencial: Usa un algoritmo de retirada exponencial para esperar períodos cada vez más largos entre los reintentos. Esto ayuda a evitar sobrecargar un servicio ya estresado. Por ejemplo, espera 1 s, luego 2 s, luego 4 s y continúa hasta una cantidad máxima de reintentos o un tiempo de espera total.
   • Jitter: Agrega una pequeña cantidad aleatoria de "jitter" a las demoras de retirada para evitar el problema de "activación simultánea" en el que muchos clientes vuelven a intentarlo de forma simultánea.

4. Registra de forma exhaustiva: Registra la respuesta de error completa, incluidos todos los detalles, en especial el ID de solicitud. Esta información es esencial para la depuración y para informar problemas al equipo de asistencia de Google si es necesario.

5. Proporciona comentarios de los usuarios: Según los códigos y mensajes específicos GoogleAdsError, proporciona comentarios claros y útiles a los usuarios de tu aplicación. Por ejemplo, en lugar de solo "Se produjo un error", puedes decir "Se requiere el nombre de la campaña" o "No se encontró el ID del grupo de anuncios proporcionado".

Si sigues estas instrucciones, podrás diagnosticar y controlar de manera eficaz los errores que muestra la API de Google Ads, lo que generará aplicaciones más estables y fáciles de usar.