Gestire gli errori dell'API

Quando invii una richiesta all'API Google Ads, questa potrebbe non riuscire per vari motivi. Ad esempio, potresti fornire un argomento non valido o il tuo account potrebbe aver raggiunto il limite per la creazione di nuove campagne. In questi casi, l'API restituisce un errore per informarti di cosa è andato storto.

Questa guida spiega come leggere e gestire gli errori dell'API in modo da poter creare applicazioni più robuste.

Struttura degli errori

Se utilizzi una delle nostre librerie client, gli errori dell'API vengono visualizzati come eccezioni. Queste eccezioni contengono dettagli che ti aiutano a capire perché si è verificato l'errore.

L'API Google Ads restituisce le informazioni sugli errori in un formato standard. Se si verifica un errore, la risposta conterrà un GoogleAdsFailure oggetto. Questo oggetto contiene un elenco di singoli GoogleAdsError oggetti, ognuno dei quali descrive in dettaglio un errore specifico.

Ogni oggetto GoogleAdsError fornisce:

• error_code: un codice di errore specifico che indica il tipo di errore, ad esempio AuthenticationError.NOT_ADS_USER.
• message: una descrizione leggibile del motivo per cui si è verificato l'errore.
• trigger: il valore che ha causato l'errore, ad esempio "1234".
• location: dettagli sulla parte della richiesta che ha causato l'errore, ad esempio un nome di campo specifico.

Oltre all'elenco degli errori, GoogleAdsFailure contiene un requestId, che è un identificatore univoco per la richiesta API che ha generato un errore.

Esempio di errore

Ecco un esempio di come appare un errore in formato JSON. Questo errore indica che il campo name di ad_group all'indice 0 non è presente nella richiesta.

{
  "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 la nostra guida per saperne di più sugli errori dell'API.

Esempi di librerie client

La sezione seguente mostra come gestire gli errori in varie librerie client.

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

Come acquisire i log

Per risolvere i problemi relativi agli errori, acquisisci i log degli errori restituiti dal server dell'API Google Ads ed esamina i relativi contenuti. Segui queste istruzioni per abilitare la registrazione e acquisire i log dell'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();

Come gestire gli errori

Se si verifica un errore, ecco i passaggi da seguire:

1. Rileva l'eccezione e acquisisci i log: inizia rilevando le eccezioni e, facoltativamente, acquisendo i log dell'API.
2. Esamina l'elenco errors: esamina ogni GoogleAdsError nell'oggetto GoogleAdsFailure. The error_code e message ti indicheranno cosa è andato storto.
3. Controlla il valore di location: il campo location può aiutarti a individuare il punto della richiesta in cui si è verificato il problema.
4. Consulta la documentazione: per codici di errore specifici, consulta la pagina degli errori comuni o il riferimento completo dei codici di errore per ulteriori dettagli sull'errore e su come correggerlo.
5. Modifica la richiesta: in base al messaggio di errore, correggi la richiesta API. Ad esempio, se vedi REQUIRED_FIELD_MISSING, assicurati di fornire questo campo nella richiesta.
6. Registra request_id: se non riesci a capire come risolvere un errore e devi contattare l'assistenza), includi i log completi di richiesta e risposta per la richiesta non riuscita. Assicurati di includere il request_id. Questo ID aiuta gli ingegneri di Google a individuare i dettagli della richiesta non riuscita nei log del server dell'API Google Ads e a esaminare il problema.

Passaggi successivi

• Consulta la pagina Errori comuni per un elenco dei problemi frequenti e delle relative soluzioni.
• Per tecniche di gestione degli errori più avanzate, tra cui la logica di nuovi tentativi e errore parziale, consulta la pagina Comprendere gli errori dell' API.