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:

Codice gRPC Codice HTTP Nome enum Descrizione Consulenza
0 200 OK Nessun errore; indica che l'operazione è riuscita. N/D
1 499 CANCELLED L'operazione è stata annullata, in genere dal client. Di solito significa che il client ha smesso di attendere. Controlla i timeout lato client.
2 500 UNKNOWN Si è verificato un errore sconosciuto. Potresti trovare ulteriori dettagli nel messaggio o nei dettagli dell'errore. Consideralo un errore del server. Spesso è possibile riprovare con il backoff.
3 400 INVALID_ARGUMENT Il client ha specificato un argomento non valido. 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: esamina i parametri della richiesta e assicurati che soddisfino i requisiti dell'API. I dettagli dell'errore in genere forniscono informazioni sull'argomento non valido e sul motivo. 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 Non è stata trovata un'entità richiesta, ad esempio una campagna o un gruppo di annunci. Errore del 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 se la risorsa esiste prima di tentare di crearla.
7 403 PERMISSION_DENIED Il chiamante non ha l'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 di autorizzazione.
8 429 RESOURCE_EXHAUSTED Una risorsa è stata esaurita (ad esempio, hai superato la quota) o un sistema è sovraccarico. Errore del client/server: in genere è necessario attendere. Implementa il backoff esponenziale e, se necessario, riduci la frequenza delle richieste. Consulta Limiti e quote delle API.
9 400 FAILED_PRECONDITION La richiesta è stata rifiutata perché il sistema non è 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 il motivo del mancato rispetto della 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 tentato di eseguire l'operazione al di fuori dell'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 è attualmente 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 e le credenziali di autenticazione. Non riprovare senza correggere l'autenticazione.

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:

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.

Indietro
Tipi di errore
Avanti
Errori comuni