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 solide in grado di gestire correttamente i problemi, dall'input non valido alla temporanea indisponibilità del servizio.

L'API Google Ads segue il modello di errore standard dell'API di Google, che si basa 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.
  • Dettagli aggiuntivi facoltativi 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 incontrare 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 interrotto l'attesa. Controlla i timeout lato client.
2 500 UNKNOWN Si è verificato un errore sconosciuto. Ulteriori dettagli potrebbero essere presenti nel messaggio di errore o nei dettagli. Trattalo come un errore del server. Spesso è possibile riprovare con il 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 di risorsa non corretto o un valore non valido. Errore del client: esamina i parametri della richiesta e assicurati che soddisfino i requisiti dell'API. I dettagli dell'errore di solito 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 è trascorsa 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 Impossibile trovare 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 correzione.
6 409 ALREADY_EXISTS L'entità che il client ha tentato di creare esiste già. Errore del client: evita di creare risorse duplicate. Verifica se la risorsa esiste prima di tentare di crearla.
7 403 PERMISSION_DENIED Il chiamante non dispone dell'autorizzazione per eseguire l'operazione specificata. Errore del 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 È stata esaurita una risorsa (ad esempio, hai superato la quota) o un sistema è sovraccarico. Errore client/server: in genere è necessario attendere. Implementa il backoff esponenziale e potenzialmente riduci il tasso di richieste. Consulta Limiti e quote API.
9 400 FAILED_PRECONDITION L'operazione è stata rifiutata perché il sistema non si trova in uno stato richiesto per l'esecuzione dell'operazione. Ad esempio, manca un campo obbligatorio. Errore del client: la richiesta è valida, ma lo stato è errato. 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, ad esempio un conflitto di transazioni. Errore del server: spesso è sicuro riprovare con un breve backoff.
11 400 OUT_OF_RANGE È stato eseguito un tentativo di operazione oltre l'intervallo valido. Errore del 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 un errore generico 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: ti consigliamo vivamente di 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 maggiori dettagli su questi codici, consulta la sezione Guida alla progettazione delle API - Codici di errore.

Informazioni sui dettagli degli errori

Oltre al codice di primo livello, l'API Google Ads fornisce informazioni più specifiche sugli errori all'interno del 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 che si è verificato.
  • 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 libreria client ti consente di accedere a questi dettagli. Ad esempio, un INVALID_ARGUMENT (codice 3) potrebbe avere GoogleAdsFailure dettagli come questi:

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

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

Individua i dettagli dell'errore

La modalità di accesso ai dettagli degli errori dipende dall'utilizzo di chiamate API standard, errori parziali o flussi di dati.

Chiamate API standard e in streaming

Quando una chiamata API non va a buon fine senza utilizzare l'errore parziale, incluse le chiamate in 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 un'eccezione con un attributo GoogleAdsFailure.

Errore parziale

Se utilizzi l'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 per le singole operazioni possono essere trovati chiamando BatchJobService.ListBatchJobResults 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 il request-id in più posizioni:

  • 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: sia per le richieste riuscite che per quelle non riuscite, request-id è disponibile anche nelle intestazioni della risposta gRPC e della risposta HTTP, ad eccezione delle richieste di streaming riuscite.
  • SearchGoogleAdsStreamResponse: per le richieste di streaming, ogni messaggio SearchGoogleAdsStreamResponse contiene un campo request_id.

Quando registri gli errori o contatti l'assistenza, assicurati di includere il 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 valori granulari error_code, message e location all'interno di GoogleAdsError forniscono le informazioni più utili per il debug e il feedback degli utenti.

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

    • Errori del client: codici come INVALID_ARGUMENT, NOT_FOUND, PERMISSION_DENIED, FAILED_PRECONDITION, UNAUTHENTICATED. Questi errori 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 indicano un problema temporaneo con il servizio API.

  3. Implementa una strategia di ripetizione dei tentativi:

    • Quando riprovare: riprova solo in caso di 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 crescenti tra i nuovi tentativi. In questo modo si evita di sovraccaricare un servizio già sotto stress. Ad esempio, attendi 1 secondo, poi 2 secondi, poi 4 secondi, continuando fino a un numero massimo di nuovi tentativi o di 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 di errore completa, inclusi tutti i dettagli, in particolare l'ID richiesta. Queste informazioni sono essenziali per il debug e per segnalare eventuali problemi all'Assistenza Google, se necessario.

  5. Fornisci un 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é limitarti a dire "Si è verificato un errore", puoi dire "Il nome della campagna è obbligatorio" 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, creando applicazioni più stabili e facili da usare.

Indietro
Tipi di errore
Avanti
Errori comuni