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 API è fondamentale per creare applicazioni robuste in grado di gestire correttamente i problemi, dall'input non valido all'indisponibilità temporanea del servizio.

L'API Google Ads segue il modello di errore standard delle API di Google, basato sui 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.
  • Facoltativi, ulteriori dettagli sull'errore.

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 generale del tipo di errore. Devi 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:

Codice gRPC Codice HTTP Nome enum Descrizione Consulenza
0 200 OK Nessun errore; indica l'esito positivo. N/D
1 499 CANCELLED L'operazione è stata annullata, in genere dal client. In genere significa che il client ha smesso di attendere. Controlla i timeout lato client.
2 500 UNKNOWN Si è verificato un errore sconosciuto. Potresti trovare maggiori dettagli nel messaggio o nei dettagli dell'errore. Considera come errore del server. Spesso può essere riprovato con backoff.
3 400 INVALID_ARGUMENT Il client ha specificato un argomento non valido. Ciò indica un problema che impedisce all'API di elaborare la richiesta, ad esempio un nome della risorsa non valido o un valore non valido. Errore del client: rivedi i parametri della richiesta e assicurati che soddisfino i requisiti dell'API. I dettagli dell'errore in genere forniscono informazioni su quale argomento non era valido e in che modo. Utilizza questi dettagli per correggere la richiesta. Non riprovare senza correggere la richiesta.
4 504 DEADLINE_EXCEEDED La scadenza è terminata prima che l'operazione potesse essere completata. Errore del server: spesso temporaneo. Valuta la possibilità di riprovare con il backoff esponenziale.
5 404 NOT_FOUND Non è stata trovata un'entità richiesta, ad esempio una campagna o un gruppo di annunci. Errore client: verifica l'esistenza e l'ID delle risorse a cui stai tentando di accedere. Non riprovare senza correggere.
6 409 ALREADY_EXISTS L'entità che il client ha tentato di creare esiste già. Errore del client: evita di creare risorse duplicate. Verifica che la risorsa esista prima di tentare di crearla.
7 403 PERMISSION_DENIED Il chiamante non dispone dell'autorizzazione per eseguire l'operazione specificata. Errore client: controlla l'autenticazione, l'autorizzazione e i ruoli utente per l'account Google Ads. Non riprovare senza risolvere i problemi relativi alle autorizzazioni.
8 429 RESOURCE_EXHAUSTED Una risorsa è stata esaurita (ad esempio, hai superato la quota) o un sistema è sovraccarico. Errore client/server: in genere richiede attesa. Implementa il backoff esponenziale e potenzialmente riduci la frequenza delle richieste. Consulta la sezione Limiti e quote API.
9 400 FAILED_PRECONDITION L'operazione è stata rifiutata perché il sistema non si trova nello stato richiesto per l'esecuzione dell'operazione. Ad esempio, manca un campo obbligatorio. Errore del client: la richiesta è valida, ma lo stato non è corretto. Esamina i dettagli dell'errore per comprendere l'errore di precondizione. Non riprovare senza correggere lo stato.
10 409 ABORTED L'operazione è stata interrotta, in genere a causa di un problema di concorrenza come un conflitto di transazioni. Errore del server: spesso è sicuro riprovare con un breve backoff.
11 400 OUT_OF_RANGE L'operazione è stata tentata oltre l'intervallo valido. Errore client: correggi l'intervallo o l'indice.
12 501 UNIMPLEMENTED L'operazione non è implementata o non è supportata dall'API. Errore del client: controlla la versione dell'API e le funzionalità disponibili. Non riprovare.
13 500 INTERNAL Si è verificato un errore interno. Si tratta di una categoria generale per i problemi lato server. Errore del server: in genere è possibile riprovare con il backoff esponenziale. Se il problema persiste, segnalalo.
14 503 UNAVAILABLE Il servizio non è al momento disponibile. Molto probabilmente si tratta di una condizione temporanea. Errore del server: è consigliabile riprovare con il backoff esponenziale.
15 500 DATA_LOSS Perdita o danneggiamento dei dati non recuperabili. Errore del server: raro. Indica un problema grave. Non riprovare. Se il problema persiste, segnalalo.
16 401 UNAUTHENTICATED La richiesta non ha credenziali di autenticazione valide. Errore del client: verifica i token di autenticazione e le credenziali. Non riprovare senza correggere l'autenticazione.

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

Informazioni sui dettagli dell'errore

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

Ogni oggetto GoogleAdsFailure contiene:

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

Ogni oggetto GoogleAdsError fornisce:

Esempio di dettagli dell'errore

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

{
  "code": 3,
  "message": "The request was invalid.",
  "details": [
    {
      "@type": "type.googleapis.com/google.ads.googleads.v17.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 dettagli di GoogleAdsFailure indicano che i campi name e description hanno causato il problema e il motivo (REQUIRED e TOO_SHORT, rispettivamente).

Individuare i dettagli dell'errore

Il modo in cui accedi ai dettagli degli errori dipende dal fatto che utilizzi 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'oggetto GoogleAdsFailure 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 mostrano come eccezione con un attributo GoogleAdsFailure.

Errore parziale

Se utilizzi l'opzione Errore parziale, gli errori relativi alle operazioni non riuscite vengono restituiti nel campo partial_failure_error della risposta, non nelle intestazioni della risposta. In questo caso, GoogleAdsFailure è incorporato in un oggetto google.rpc.Status nella risposta.

Job batch

Per l'elaborazione batch, gli errori relativi alle singole operazioni possono essere trovati 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

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

Puoi trovare request-id in più punti:

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

Quando registri 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'oggetto Status, cercando in particolare GoogleAdsFailure. I campi granulari errorCode, message e location all'interno di GoogleAdsError forniscono le 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 ripetizione dei tentativi:

    • Quando riprovare: riprova solo in caso di errori del server temporanei, ad esempio UNAVAILABLE, DEADLINE_EXCEEDED, INTERNAL, UNKNOWN e ABORTED.
    • Backoff esponenziale: utilizza un algoritmo di backoff esponenziale per attendere periodi sempre più lunghi tra i tentativi. In questo modo si evita di sovraccaricare un servizio già sotto stress. Ad esempio, attendi 1 secondo, poi 2 secondi, poi 4 secondi, fino a un numero massimo di tentativi o un 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 i log in modo completo: registra l'intera risposta di errore, inclusi tutti i dettagli, in particolare l'ID richiesta. Queste informazioni sono essenziali per il debug e per segnalare problemi all'assistenza Google, se necessario.

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

Se segui queste linee guida, puoi diagnosticare e gestire in modo efficace gli errori restituiti dall'API Google Ads, ottenendo applicazioni più stabili e facili da usare.