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 para crear campañas nuevas. En esos casos, la API muestra un error para informarte qué sucedió.

En esta guía, se explica cómo leer y controlar los errores de la API para que puedas crear 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 muestra información de errores en un formato estándar. Si se produce un error, la respuesta contendrá un GoogleAdsFailure objeto. Este objeto contiene una lista de objetos individuales GoogleAdsError, cada uno de los cuales detalla un error específico.

Cada objeto GoogleAdsError proporciona lo siguiente:

• error_code: Un código de error específico que te indica el tipo de error, como AuthenticationError.NOT_ADS_USER.
• message: Una descripción legible de por qué se produjo el error.
• trigger: El valor que causó el error, como "1234".
• location: 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 del 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.v25.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 errores, captura los registros de errores que muestra el servidor de la API de Google Ads y examina su contenido. Usa las siguientes instrucciones para habilitar el registro y capturar 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 errores

Si encuentras un error, sigue estos pasos:

1. Captura la excepción y los registros: Comienza por capturar las excepciones y, de manera opcional, los registros de la API.
2. Examina la lista errors: Observa cada GoogleAdsError en el objeto GoogleAdsFailure. El error_code y el message te indicarán qué sucedió.
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 completa de códigos de error 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 request. Por ejemplo, si ves REQUIRED_FIELD_MISSING, asegúrate de proporcionar ese campo en tu solicitud.
6. Registra el request_id: Si no puedes determinar cómo resolver un error y necesitas comunicarte con el equipo de asistencia), incluye los registros completos de solicitud y respuesta para la solicitud fallida. Asegúrate de incluir el 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

• Consulta Errores comunes para obtener una lista de problemas frecuentes y sus soluciones.
• Para obtener técnicas más avanzadas de manejo de errores, incluida la lógica de reintento y la falla parcial, consulta Comprende los errores de la API.