Maneja errores de API

Cuando envías una solicitud a la API de Google Ads, es posible que falle por varios motivos. Por ejemplo, es posible que proporciones un argumento no válido o que tu cuenta haya alcanzado el límite de creación de 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 del error

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é ocurrió el error.

La API de Google Ads devuelve información de errores 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 de los cuales detalla un error específico.

Cada objeto GoogleAdsError proporciona lo siguiente:

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

Además de la lista de errores, GoogleAdsFailure contiene un requestId, que es un identificador único para la solicitud de 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 del objeto ad_group en el índice 0 de la solicitud.

{
  "code": 3,
  "message": "Request contains an invalid argument.",
  "details": [
    {
      "@type": "type.googleapis.com/google.ads.googleads.v22.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 nuestra guía 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.

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);
  }
}

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}");
    }
}

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
    );
    foreach ($googleAdsException->getGoogleAdsFailure()->getErrors() as $error) {
        /** @var GoogleAdsError $error */
        printf(
            "\t%s: %s%s",
            $error->getErrorCode()->getErrorCode(),
            $error->getMessage(),
            PHP_EOL
        );
    }
}

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 '{error.error_code}'.")

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

# 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 relacionados con errores, captura los registros de errores que devuelve el servidor de la API de Google Ads y analiza su contenido. Sigue las instrucciones que se indican a continuación para habilitar el registro y capturar los registros de la API.

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

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

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

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, captura 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. Comprueba el valor de location: El campo location puede ayudarte a identificar en qué parte de la solicitud ocurrió el problema.
4. Consulta la documentación: Para obtener más detalles sobre errores específicos y cómo corregirlos, consulta la página de errores comunes o la referencia completa de códigos de error.
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 resolver un error y necesitas comunicarte con el equipo de asistencia, incluye los registros completos de la solicitud y la respuesta de la solicitud que falló. Asegúrate de incluir request_id. Este ID ayuda a los ingenieros de Google a ubicar los detalles de la solicitud fallida en los registros del servidor de la API de Google Ads y a investigar tu problema.

Próximos pasos

• Revisa Errores comunes para ver una lista de los problemas frecuentes y sus soluciones.
• Para conocer técnicas más avanzadas de manejo de errores, incluida la lógica de reintento y la falla parcial, consulta Cómo comprender los errores de la API.