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 crear 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 las APIs 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:

  • Es un código de error numérico.
  • Es un mensaje de error.
  • Son detalles adicionales opcionales del error.

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 primero este código numérico 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:

Código de gRPC Código HTTP Nombre de la enumeración Descripción Orientación
0 200 OK No hay errores, lo que indica que la operación se realizó correctamente. N/A
1 499 CANCELLED La operación se canceló (por lo general, la cancela el cliente). Por lo general, significa que el cliente dejó de esperar. Verifica los tiempos de espera del cliente.
2 500 UNKNOWN Se produjo un error desconocido. Es posible que haya más detalles en el mensaje o los detalles del error. Se trata como un error del servidor. A menudo, se puede volver a intentar con una retirada.
3 400 INVALID_ARGUMENT El cliente especificó un argumento no válido. Esto indica un problema que impide que la API procese la solicitud, como un nombre de recurso con formato incorrecto o un valor no válido. Error del cliente: Revisa los parámetros de tu solicitud y asegúrate de que cumplan con los requisitos de la API. Por lo general, los detalles del error proporcionan información sobre qué argumento no era válido y por qué. Usa estos detalles para corregir la solicitud. No vuelvas a intentar la operación sin corregir la solicitud.
4 504 DEADLINE_EXCEEDED El plazo venció antes de que la operación se pudiera completar. Error del servidor: Suele ser transitorio. Considera volver a intentarlo con una retirada exponencial.
5 404 NOT_FOUND No se encontró alguna entidad solicitada, como una campaña o un grupo de anuncios. Error del cliente: Verifica la existencia y el ID de los recursos a los que intentas acceder. No vuelvas a intentar la operación sin corregir el problema.
6 409 ALREADY_EXISTS Ya existe la entidad que el cliente intentó crear. Error del cliente: Evita crear recursos duplicados. Verifica si el recurso existe antes de intentar crearlo.
7 403 PERMISSION_DENIED El emisor de la llamada no tiene permiso para ejecutar la operación especificada. Error del cliente: Verifica la autenticación, la autorización y los roles de usuario de la cuenta de Google Ads. No vuelvas a intentarlo sin resolver los permisos.
8 429 RESOURCE_EXHAUSTED Se agotó un recurso (por ejemplo, superaste tu cuota) o se sobrecargó un sistema. Error de cliente o servidor: Por lo general, requiere esperar. Implementa la retirada exponencial y, posiblemente, reduce la frecuencia de solicitudes. Consulta Límites y cuotas de la API.
9 400 FAILED_PRECONDITION La operación se rechazó debido a que el sistema no se encuentra en un estado necesario para la ejecución de la operación. Por ejemplo, falta un campo obligatorio. Error del cliente: La solicitud es válida, pero el estado es incorrecto. Revisa los detalles del error para comprender la falla de la condición previa. No vuelvas a intentar la operación sin corregir el estado.
10 409 ABORTED La operación se anuló, por lo general, debido a un problema de simultaneidad, como un conflicto de transacción. Error del servidor: A menudo, es seguro volver a intentarlo con una retirada breve.
11 400 OUT_OF_RANGE La operación se intentó fuera del rango válido. Error del cliente: Corrige el rango o el índice.
12 501 UNIMPLEMENTED La operación no se implementó o no es compatible con la API. Error del cliente: Verifica la versión de la API y las funciones disponibles. No volver a intentar.
13 500 INTERNAL Se produjo un error interno. Este es un mensaje general para todos los problemas del servidor. Error del servidor: Por lo general, se puede volver a intentar con una retirada exponencial. Si el problema persiste, infórmalo.
14 503 UNAVAILABLE El servicio no está disponible actualmente. Lo más probable es que se trate de una condición transitoria. Error del servidor: Se recomienda volver a intentarlo con una retirada exponencial.
15 500 DATA_LOSS Daño o pérdida de datos no recuperable. Error del servidor: Es poco frecuente. Indica un problema grave. No volver a intentar. Si el problema persiste, infórmalo.
16 401 UNAUTHENTICATED La solicitud no tiene credenciales de autenticación válidas. Error del cliente: Verifica tus tokens de autenticación y credenciales. No vuelvas a intentarlo sin corregir la autenticación.

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

Comprende los detalles del error

Más allá del código de nivel superior, la API de Google Ads proporciona información de error más específica dentro del campo details del objeto Status. Este campo suele contener un prototipo de GoogleAdsFailure, que incluye una lista de objetos GoogleAdsError individuales.

Cada objeto GoogleAdsFailure contiene lo siguiente:

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

Cada objeto GoogleAdsError proporciona lo siguiente:

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 los siguientes:

{
  "code": 3,
  "message": "The request was invalid.",
  "details": [
    {
      "@type": "type.googleapis.com/google.ads.googleads.v17.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 detalles de GoogleAdsFailure te indican que los campos name y description causaron el problema y por qué (REQUIRED y TOO_SHORT, respectivamente).

Cómo encontrar 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 la falla parcial, incluidas las llamadas de transmisión, el objeto GoogleAdsFailure se devuelve como parte de los metadatos finales en los encabezados de respuesta de gRPC. Si usas REST para las llamadas estándar, GoogleAdsFailure se devuelve en la respuesta HTTP. Las bibliotecas cliente suelen mostrar esto como una excepción con un atributo GoogleAdsFailure.

Falla parcial

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

los trabajos por lotes

En el caso del procesamiento por lotes, los errores de las operaciones individuales se pueden encontrar recuperando los resultados del trabajo por lotes después de que se complete 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 fundamental para solucionar problemas.

Puedes encontrar el archivo request-id en varios lugares:

  • GoogleAdsFailure: Si falla una llamada a la API y se devuelve GoogleAdsFailure, 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 también está disponible en los encabezados de respuesta de gRPC y HTTP, con la excepción de las solicitudes de transmisión exitosas.
  • SearchGoogleAdsStreamResponse: Para las solicitudes de transmisión, cada mensaje SearchGoogleAdsStreamResponse contiene un campo request_id.

Cuando registres errores o te comuniques con el equipo de asistencia, asegúrate de incluir el request-id para facilitar el diagnóstico de los problemas.

Prácticas recomendadas para el manejo de errores

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

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

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

    • Errores del cliente: Códigos como INVALID_ARGUMENT, NOT_FOUND, PERMISSION_DENIED, FAILED_PRECONDITION y UNAUTHENTICATED. Estos errores 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 y UNKNOWN. Esto sugiere que hay un problema temporal con el servicio de la API.

  3. Implementa una estrategia de reintento:

    • Cuándo reintentar: Reintenta solo en caso de 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 que ya está estresado. Por ejemplo, espera 1 s, luego 2 s, luego 4 s y así sucesivamente hasta alcanzar 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 reintentan la operación de forma simultánea.

  4. Registra todo: Registra la respuesta de error completa, incluidos todos los detalles, en especial el ID de la 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 a los usuarios: Según los códigos y mensajes específicos de GoogleAdsError, proporciona comentarios claros y útiles a los usuarios de tu aplicación. Por ejemplo, en lugar de decir 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 estos lineamientos, podrás diagnosticar y controlar de manera eficaz los errores que devuelve la API de Google Ads, lo que generará aplicaciones más estables y fáciles de usar.