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 de forma correcta, 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.
  • Es un mensaje de error.
  • 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 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:

Código de gRPC Código HTTP Nombre de la enum Descripción Orientación
0 200 OK No hay error; indica que la operación se realizó correctamente. N/A
1 499 CANCELLED La operación se canceló (en 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 de error o en los detalles. Trátalo como un error de 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. Los detalles del error suelen proporcionar información sobre qué argumento no era válido y cómo. 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 de 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 intentarlo sin corregir el problema.
6 409 ALREADY_EXISTS La entidad que el cliente intentó crear ya existe. 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 intentar la operación sin resolver los permisos.
8 429 RESOURCE_EXHAUSTED Se agotó un recurso (por ejemplo, superaste tu cuota) o un sistema está sobrecargado. Error de cliente o servidor: Por lo general, requiere esperar. Implementa la retirada exponencial y, posiblemente, reduce el porcentaje 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ó. Esto suele ocurrir debido a un problema de simultaneidad, como un conflicto de transacciones. Error de servidor: Por lo general, 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 vuelvas a intentarlo.
13 500 INTERNAL Se produjo un error interno. Este es un mensaje general para todos los problemas del servidor. Error de 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 temporalmente. Lo más probable es que se trate de una condición transitoria. Error de servidor: Se recomienda volver a intentarlo con una retirada exponencial.
15 500 DATA_LOSS Daño o pérdida de datos no recuperable. Error de servidor: Poco frecuente. Indica un problema grave. No vuelvas a intentarlo. 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 intentar la operación 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

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

Cada objeto GoogleAdsFailure contiene lo siguiente:

  • errors: Es una lista de objetos GoogleAdsError, cada uno con detalles de un error específico que se produjo.
  • request_id: Es un ID único para la solicitud, útil para fines de depuración y 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) puede tener detalles de GoogleAdsFailure como los siguientes:

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

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).

Ubica los detalles del error

La forma en que accedes a los detalles de los errores 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 una llamada a la API falla sin usar un error 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 llamadas estándar, se devuelve GoogleAdsFailure en la respuesta HTTP. Por lo general, las bibliotecas cliente muestran esto como una excepción con un atributo GoogleAdsFailure.

Falla parcial

Si usas la falla parcial, los errores de las operaciones con errores se devuelven en el campo partial_failure_error de la respuesta, no en los encabezados de respuesta. En este caso, el GoogleAdsFailure se incorpora 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 llamando a BatchJobService.ListBatchJobResults después de que se complete el trabajo. Cada resultado de la operación incluirá un campo status con 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 una llamada a la API falla 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: Tanto para las solicitudes exitosas como para las fallidas, request-id también está disponible en los encabezados de respuesta HTTP y gRPC, con la excepción de las solicitudes de transmisión exitosas.
  • SearchGoogleAdsStreamResponse: En el caso de 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 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: Analiza siempre el campo details del objeto Status, en especial, busca GoogleAdsFailure. Los valores detallados de error_code, message y location 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 de cliente de los de 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 de servidor: Códigos como UNAVAILABLE, INTERNAL, DEADLINE_EXCEEDED y UNKNOWN. Esto sugiere un problema temporal con el servicio de la API.

  3. Implementa una estrategia de reintentos:

    • Cuándo reintentar: Reintenta solo en caso de errores de servidor transitorios, 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á sobrecargado. 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.
    • Fluctuación: Agrega una pequeña cantidad aleatoria de "fluctuación" a los retrasos de la retirada para evitar el problema de "activación simultánea" en el que muchos clientes vuelven a intentarlo al mismo tiempo.

  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 depurar y informar problemas al equipo de Atención al cliente de Google si es necesario.

  5. Proporciona comentarios de 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 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.

Anterior
Tipos de errores
Siguiente
Errores comunes