Informazioni sugli errori API

Questa guida spiega come l'API Google Ads gestisce e comunica gli errori. Comprendere la struttura e il significato degli errori dell'API è fondamentale per creare applicazioni robuste in grado di gestire senza problemi i problemi, dall'input non valido alla mancata disponibilità temporanea del servizio.

L'API Google Ads segue il modello di errore standard delle API di Google, basato su codici di stato gRPC. Ogni risposta dell'API che genera un errore include un oggetto Status contenente:

• Un codice di errore numerico.
• Un messaggio di errore.
• Dettagli aggiuntivi sull'errore (facoltativi).

Codici di errore canonici

L'API Google Ads utilizza un insieme di codici di errore canonici definiti da gRPC e HTTP. Questi codici forniscono un'indicazione di alto livello del tipo di errore. Dovresti sempre controllare prima questo codice numerico per comprendere la natura fondamentale del problema.

La tabella seguente riassume i codici più comuni che potresti riscontrare quando utilizzi l'API Google Ads:

Per ulteriori dettagli su questi codici, consulta la Guida alla progettazione delle API - Codici di errore.

Comprendere i dettagli dell'errore

Oltre al codice di primo livello, l'API Google Ads fornisce informazioni più specifiche sull'errore nel campo details dell'oggetto Status. Questo campo spesso contiene un GoogleAdsFailure proto, che include un elenco di singoli GoogleAdsError oggetti.

Ogni GoogleAdsFailure oggetto contiene:

• errors: un elenco di oggetti GoogleAdsError, ognuno dei quali descrive un errore specifico che si è verificato.
• request_id: un ID univoco per la richiesta, utile per il debug e l'assistenza.

Ogni GoogleAdsError oggetto fornisce:

• errorCode: un codice di errore più granulare, specifico dell'API Google Ads, ad esempio AuthenticationError.NOT_ADS_USER.
• message: una descrizione leggibile dell'errore specifico.
• trigger: il valore che ha causato l'errore, se applicabile.
• location: descrive la posizione in cui si è verificato l'errore nella richiesta, inclusi i percorsi dei campi.
• details: dettagli aggiuntivi sull'errore, ad esempio i motivi dell'errore non pubblicati.

Esempio di dettagli dell'errore

Quando ricevi un errore, la libreria client ti consentirà di accedere a questi dettagli. Ad esempio, un INVALID_ARGUMENT (codice 3) potrebbe avere dettagli GoogleAdsFailure come i seguenti:

{
  "code": 3,
  "message": "The request was invalid.",
  "details": [
    {
      "@type": "type.googleapis.com/google.ads.googleads.v24.errors.GoogleAdsFailure",
      "errors": [
        {
          "errorCode": {
            "fieldError": "REQUIRED"
          },
          "message": "The required field was not present.",
          "location": {
            "fieldPathElements": [
              { "fieldName": "operations" },
              { "fieldName": "create" },
              { "fieldName": "name" }
            ]
          }
        },
        {
          "errorCode": {
            "stringLengthError": "TOO_SHORT"
          },
          "message": "The provided string is too short.",
          "trigger": {
            "stringValue": ""
          },
          "location": {
            "fieldPathElements": [
              { "fieldName": "operations" },
              { "fieldName": "create" },
              { "fieldName": "description" }
            ]
          }
        }
      ]
    }
  ]
}

In questo esempio, nonostante INVALID_ARGUMENT di primo livello, i GoogleAdsFailure dettagli indicano che i name e description campi hanno causato il problema e il motivo (REQUIRED e TOO_SHORT, rispettivamente).

Individuare i dettagli dell'errore

La modalità di accesso ai dettagli dell'errore dipende dal fatto che tu stia utilizzando chiamate API standard, errori parziali o streaming.

Chiamate API standard e di streaming

Quando una chiamata API non riesce senza utilizzare l'errore parziale, incluse le chiamate di streaming, l' GoogleAdsFailure oggetto viene restituito come parte dei metadati finali nelle intestazioni della risposta gRPC. Se utilizzi REST per le chiamate standard, GoogleAdsFailure viene restituito nella risposta HTTP. Le librerie client in genere lo visualizzano come un'eccezione con un GoogleAdsFailure attributo.

Errore parziale

Se utilizzi errore parziale, gli errori per le operazioni non riuscite vengono restituiti nel campo partial_failure_error della risposta, non nelle intestazioni della risposta. In questo caso, il GoogleAdsFailure è incorporato in un oggetto google.rpc.Status nella risposta.

Job batch

Per l'elaborazione batch, gli errori per le singole operazioni sono disponibili recuperando i risultati del job batch al termine del job. Ogni risultato dell'operazione includerà un campo status contenente i dettagli dell'errore se l'operazione non è riuscita.

ID richiesta

request-id è una stringa univoca che identifica la tua richiesta API ed è essenziale per la risoluzione dei problemi.

Puoi trovare request-id in più posizioni:

• GoogleAdsFailure: se una chiamata API non riesce e GoogleAdsFailure viene restituito, conterrà un request_id.
• Metadati finali: sia per le richieste riuscite che per quelle non riuscite, request-id è disponibile nei metadati finali della risposta gRPC.
• Intestazioni della risposta: sia per le richieste riuscite che per quelle non riuscite, request-id è disponibile anche nelle intestazioni della risposta gRPC e nelle risposte HTTP, ad eccezione delle richieste di streaming riuscite.
• SearchGoogleAdsStreamResponse: per le richieste di streaming, ogni SearchGoogleAdsStreamResponse messaggio contiene un campo request_id.

Quando registri gli errori o contatti l'assistenza, assicurati di includere request-id per facilitare la diagnosi dei problemi.

Best practice per la gestione degli errori

Per creare applicazioni resilienti, implementa le seguenti best practice:

1. Esamina i dettagli dell'errore: analizza sempre il campo details dell'Status oggetto, in particolare cercando GoogleAdsFailure. The granular errorCode, message, and location within GoogleAdsError provide the informazioni più utili per il debug e il feedback degli utenti.

2. Distinguere gli errori del client da quelli del server:

   • Errori del client: codici come INVALID_ARGUMENT, NOT_FOUND, PERMISSION_DENIED, FAILED_PRECONDITION, UNAUTHENTICATED. Questi richiedono modifiche alla richiesta o allo stato/alle credenziali dell'applicazione. Non riprovare a inviare la richiesta senza risolvere il problema.
   • Errori del server: codici come UNAVAILABLE, INTERNAL, DEADLINE_EXCEEDED, UNKNOWN. Questi suggeriscono un problema temporaneo con il servizio API.

3. Implementa una strategia di nuovi tentativi:

   • Quando riprovare: riprova solo per gli errori temporanei del server, ad esempio UNAVAILABLE, DEADLINE_EXCEEDED, INTERNAL, UNKNOWN e ABORTED.
   • Backoff esponenziale: utilizza un algoritmo di backoff esponenziale per attendere periodi di tempo sempre più lunghi tra i nuovi tentativi. In questo modo, eviti di sovraccaricare un servizio già sotto stress. Ad esempio, attendi 1 secondo, poi 2 secondi, poi 4 secondi e così via fino a un numero massimo di nuovi tentativi o al tempo di attesa totale.
   • Jitter: aggiungi una piccola quantità casuale di "jitter" ai ritardi di backoff per evitare il problema del "thundering herd", in cui molti client riprovano contemporaneamente.

4. Registra in modo completo: registra la risposta completa all'errore, inclusi tutti i dettagli, in particolare l'ID richiesta. Queste informazioni sono essenziali per il debug e per segnalare i problemi all'assistenza Google, se necessario.

5. Fornisci feedback agli utenti: in base ai codici e ai messaggi specifici GoogleAdsError, fornisci un feedback chiaro e utile agli utenti della tua applicazione. Ad esempio, anziché dire semplicemente "Si è verificato un errore", puoi dire "Il nome della campagna è obbligatorio" o "Non è stato trovato l'ID gruppo di annunci fornito".

Seguendo queste linee guida, puoi diagnosticare e gestire in modo efficace gli errori restituiti dall'API Google Ads, ottenendo applicazioni più stabili e intuitive.