Gestire gli errori dell'API

Quando invii una richiesta all'API Google Ads, l'operazione 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 farti sapere cosa è andato storto.

Questa guida spiega come leggere e gestire gli errori API per creare applicazioni più robuste.

Struttura dell'errore

Se utilizzi una delle nostre librerie client, gli errori 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 oggetto GoogleAdsFailure. Questo oggetto contiene un elenco di singoli oggetti GoogleAdsError, ognuno dei quali descrive 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, ovvero un identificatore univoco per la richiesta API che ha generato un errore.

Errore di esempio

Ecco un esempio di 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.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"
    }
  ]
}

Per scoprire di più sugli errori delle API, consulta la nostra guida.

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 e controllane i contenuti. Segui queste istruzioni per abilitare la registrazione e acquisire i log 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 riscontri un errore, ecco i passaggi da seguire:

1. Rileva l'eccezione e acquisisci i log: inizia rilevando le eccezioni e, se vuoi, acquisisci i log API.
2. Esamina l'elenco errors: esamina ogni GoogleAdsError nell'oggetto GoogleAdsFailure. error_code e message ti diranno cosa non ha funzionato.
3. Controlla il valore location: il campo location può aiutarti a individuare in quale punto della richiesta si è verificato il problema.
4. Consulta la documentazione: per codici di errore specifici, consulta la pagina degli errori comuni o il riferimento completo ai codici di errore per maggiori 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 tua richiesta.
6. Registra request_id: se non riesci a capire come risolvere un errore e devi contattare l'assistenza, includi i log completi di richieste e risposte per la richiesta non riuscita. Assicurati di includere 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 sezione 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 ripetizione e l'errore parziale, consulta Informazioni sugli errori dell'API.