Maneja errores de API

Cuando envías una solicitud a la API de Google Ads, esta puede fallar por varios motivos. Por ejemplo, es posible que proporciones un argumento no válido o que tu cuenta haya alcanzado el límite para crear campañas nuevas. En estos casos, la API devuelve un error para informarte qué salió mal.

En esta guía, se explica cómo leer y controlar los errores de la API para que puedas compilar aplicaciones más sólidas.

Estructura de errores

Si usas una de nuestras bibliotecas cliente, los errores de la API se muestran como excepciones. Estas excepciones contienen detalles que te ayudan a comprender por qué se produjo el error.

La API de Google Ads devuelve información de error en un formato estándar. Si se produce un error, la respuesta contendrá un objeto GoogleAdsFailure. Este objeto contiene una lista de objetos GoogleAdsError individuales, cada uno con detalles de un error específico.

Cada objeto GoogleAdsError proporciona lo siguiente:

  • error_code: Es un código de error específico que te indica el tipo de error, como AuthenticationError.NOT_ADS_USER.
  • message: Es una descripción legible por humanos de por qué se produjo el error.
  • trigger: Es el valor que causó el error, como "1234".
  • location: Son los detalles sobre qué parte de la solicitud causó el error, como un nombre de campo específico.

Además de la lista de errores, GoogleAdsFailure contiene un requestId, que es un identificador único para la solicitud a la API que generó un error.

Ejemplo de error

Este es un ejemplo de cómo se ve un error en formato JSON. Este error indica que falta el campo name de ad_group en el índice 0 en la solicitud.

{
  "code": 3,
  "message": "Request contains an invalid argument.",
  "details": [
    {
      "@type": "type.googleapis.com/google.ads.googleads.v26.errors.GoogleAdsFailure",
      "errors": [
        {
          "errorCode": {
            "requestError": "REQUIRED_FIELD_MISSING"
          },
          "message": "Required field is missing",
          "location": {
            "fieldPathElements": [
              {
                "fieldName": "ad_group",
                "index": 0
              },
              {
                "fieldName": "name"
              }
            ]
          }
        }
      ],
      "requestId": "unique_request_id_12345"
    }
  ]
}

Consulta Información sobre los errores de la API para obtener más información sobre los errores de la API.

Ejemplos de bibliotecas cliente

En la siguiente sección, se muestra cómo controlar errores en varias bibliotecas cliente.

Java

try {
  // Make an API call.
  ...
} catch (GoogleAdsException gae) {
  // GoogleAdsException is the base class for most exceptions thrown by an
  // API request. Instances of this exception have a message and a
  // GoogleAdsFailure that contains a collection of GoogleAdsErrors that
  // indicate the underlying causes of the GoogleAdsException.
  System.err.printf(
      "Request ID %s failed due to GoogleAdsException. Underlying"
          + " errors:%n",
      gae.getRequestId());
  int i = 0;
  for (GoogleAdsError googleAdsError :
      gae.getGoogleAdsFailure().getErrorsList()) {
    System.err.printf("  Error %d: %s%n", i++, googleAdsError);
  }
}

C#

try
{
    // Make an API call.
    ...
}
catch (GoogleAdsException e)
{
    Console.WriteLine($"Request with ID '{e.RequestId}' has failed.");
    Console.WriteLine("Google Ads failure details:");

    foreach (GoogleAdsError error in e.Failure.Errors)
    {
        Console.WriteLine($"{error.ErrorCode}: {error.Message}");
    }
}

PHP

try {
    // Make an API call.
    ...
} catch (GoogleAdsException $googleAdsException) {
    printf(
        "Request with ID '%s' has failed.%sGoogle Ads failure details:%s",
        $googleAdsException->getRequestId(),
        PHP_EOL,
        PHP_EOL
    );
    $errors = $googleAdsException->getGoogleAdsFailure()->getErrors();
    foreach ($errors as $error) {
        /** @var GoogleAdsError $error */
        printf(
            "\t%s: %s%s",
            $error->getErrorCode()->getErrorCode(),
            $error->getMessage(),
            PHP_EOL
        );
    }
}

Python

try:
    # Make an API call.
    ...
except GoogleAdsException as ex:
    print(
        f"Request with ID '{ex.request_id}' failed with status "
        f"'{ex.error.code().name}' and includes the following errors:"
    )
    for error in ex.failure.errors:
        print(
            f"\tError with message '{error.message}' and code "
            f"'{error.error_code}'."
        )

Ruby

begin
  # Make an API call.
  ...
rescue Google::Ads::GoogleAds::Errors::GoogleAdsError => e
  puts "API call failed with request ID: #{e.request_id}"
  e.failure.errors.each do |error|
    puts "\t#{error.error_code}: #{error.message}"
  end
end

Perl

# Try sending a mutate request to add the ad group ad.
...
if ($response->isa("Google::Ads::GoogleAds::GoogleAdsException")) {
  printf "Google Ads failure details:\n";
  foreach my $error (@{$response->get_google_ads_failure()->{errors}}) {
    printf "\t%s: %s\n",
      [keys %{$error->{errorCode}}]->[0], $error->{message};
  }
}

Cómo capturar registros

Para solucionar problemas, captura los registros de errores que devuelve el servidor de la API de Google Ads e inspecciona su contenido. Usa las siguientes instrucciones para habilitar el registro y capturar los registros de la API.

Java

Consulta la guía de registro de la biblioteca cliente de Java para obtener instrucciones.

C#

Para inicializar el registro, agrega la siguiente línea en tu método Main antes de realizar llamadas a la API. Esto garantiza que la biblioteca genere registros para todas las llamadas a la API que realice tu aplicación.

using Google.Ads.GoogleAds.Util;
...

// Detailed logs.
TraceUtilities.Configure(TraceUtilities.DETAILED_REQUEST_LOGS_SOURCE,
    "/path/to/your/logs/details.log", System.Diagnostics.SourceLevels.All);

// Summary logs.
TraceUtilities.Configure(TraceUtilities.SUMMARY_REQUEST_LOGS_SOURCE,
    "/path/to/your/logs/summary.log", System.Diagnostics.SourceLevels.All);

Consulta la guía de registro de la biblioteca de .NET para obtener opciones adicionales.

PHP

Puedes establecer la configuración de registro en el archivo google_ads_php.ini de tu biblioteca cliente. Establece logLevel en NOTICE para comenzar a capturar los registros de errores detallados.

[LOGGING]
; Optional logging settings.
logFilePath = "path/to/your/file.log"
logLevel = "NOTICE"

Consulta la guía de registro de la biblioteca cliente de PHP para obtener instrucciones.

Python

Puedes establecer la configuración de registro en el archivo google-ads.yaml de tu biblioteca cliente. Establece el nivel de registro en DEBUG para comenzar a capturar los registros de errores detallados.

Consulta la guía de registro de la biblioteca de Python para obtener opciones adicionales.

Ruby

Puedes establecer la configuración de registro en el archivo google_ads_config.rb de tu biblioteca cliente. Establece el nivel de registro en INFO para comenzar a capturar los registros de errores detallados.

Consulta la guía de registro de la biblioteca de Ruby para obtener opciones adicionales.

Perl

Para inicializar el registro, agrega la siguiente línea en tu secuencia de comandos de Perl antes de realizar cualquier llamada a la API.

Google::Ads::GoogleAds::Logging::GoogleAdsLogger::enable_all_logging();

Consulta la guía de registro de la biblioteca de Perl para obtener más opciones.

curl

De forma predeterminada, curl imprime las respuestas con errores en stderr.

Cómo controlar los errores

Si encuentras un error, sigue estos pasos:

  1. Detecta la excepción y captura los registros: Comienza por detectar las excepciones y, de manera opcional, capturar los registros de la API.
  2. Examina la lista errors: Observa cada GoogleAdsError en el objeto GoogleAdsFailure. error_code y message te indicarán qué salió mal.
  3. Verifica el valor de location: El campo location puede ayudarte a identificar en qué parte de la solicitud se produjo el problema.
  4. Consulta la documentación: Para obtener códigos de error específicos, consulta la página de errores comunes o la referencia de códigos de error completa para obtener más detalles sobre el error y cómo corregirlo.
  5. Ajusta tu solicitud: Según el mensaje de error, corrige tu solicitud a la API. Por ejemplo, si ves REQUIRED_FIELD_MISSING, asegúrate de proporcionar ese campo en tu solicitud.
  6. Registra el request_id: Si no puedes averiguar cómo resolver un error y necesitas comunicarte con el equipo de asistencia, incluye los registros completos de solicitudes y respuestas de la solicitud con errores. Asegúrate de incluir el request_id. Este ID ayuda a los ingenieros de Google a encontrar los detalles de la solicitud con errores en los registros del servidor de la API de Google Ads y a investigar tu problema.

Próximos pasos

Anterior
Guía de inicio rápido
Siguiente
Errores comunes