Tipi di errore

Abbiamo suddiviso gli errori nelle seguenti categorie generali:

  • Autenticazione
  • Errori per cui è possibile riprovare
  • Convalida
  • Problemi relativi alla sincronizzazione

Sebbene queste categorie non comprendano tutti i possibili errori e alcuni possano rientrare in più di una categoria, possono comunque fungere da punto di partenza per strutturare la gestione degli errori della tua app. Per ulteriori dettagli su errori specifici, consulta le seguenti risorse:

  • La sezione Errori comuni fornisce ulteriori dettagli su un determinato errore.
  • google.rpc.Status fornisce dettagli sul modello di errore logico utilizzato dall'API.
  • Codici di errore canonici fornisce un elenco e una spiegazione dei codici di errore canonici definiti da gRPC e HTTP nel contesto dell'API Google Ads.

Errori di autenticazione

L'autenticazione indica se la tua app ha ricevuto l'autorizzazione da un utente per accedere a Google Ads per suo conto. L'autenticazione viene gestita tramite le credenziali generate dal flusso OAuth2.

Il motivo più comune per cui si verifica un errore di autenticazione dovuto a fattori al di fuori del tuo controllo è che l'utente autenticato ha revocato l'autorizzazione concessa alla tua app per agire per suo conto. Ad esempio, se la tua app gestisce account Google Ads separati per clienti indipendenti ed esegue l'autenticazione separatamente per ogni cliente durante la gestione del suo account, un cliente potrebbe revocare l'accesso della tua app in qualsiasi momento. A seconda di quando è stato revocato l'accesso, l'API potrebbe restituire direttamente un errore AuthenticationError.OAUTH_TOKEN_REVOKED oppure gli oggetti delle credenziali integrati nelle librerie client potrebbero generare un'eccezione di token revocato. In entrambi i casi, se la tua app ha un'interfaccia utente per i tuoi clienti, potrebbe chiedere loro di riavviare il flusso OAuth2 per ristabilire l'autorizzazione della tua app ad agire per loro conto.

Analogamente, se il tuo progetto Google Cloud ha solo il livello di accesso di test e tenta di effettuare richieste a un account di produzione (non di test), l'API restituisce un AuthorizationError il cui valore enum dipende dalla versione dell'API:

Errori per cui è possibile riprovare

Alcuni errori, come TRANSIENT_ERROR o INTERNAL_ERROR, possono indicare un problema temporaneo che potrebbe essere risolto riprovando la richiesta dopo una breve pausa.

Per le richieste avviate dall'utente, una strategia consiste nell'indicare immediatamente un errore nella UI e offrire all'utente l'opzione di attivare un nuovo tentativo. In alternativa, l'app potrebbe prima riprovare automaticamente a inviare la richiesta, mostrando l'errore nell'interfaccia utente solo dopo aver raggiunto un numero massimo di nuovi tentativi o un tempo di attesa totale dell'utente.

Per le richieste avviate sul backend, l'app deve riprovare automaticamente a inviare la richiesta fino a un numero massimo di tentativi.

Quando riprovi le richieste, utilizza una policy di backoff esponenziale con jitter randomizzato. Ad esempio, se la prima volta aspetti 5 secondi prima di riprovare, potresti aspettare 10 secondi dopo il secondo tentativo e 20 secondi dopo il terzo, aggiungendo un piccolo ritardo casuale a ogni intervallo per evitare picchi di tentativi sincronizzati. Il backoff esponenziale contribuisce a garantire che l'API non venga chiamata in modo troppo aggressivo. Se un errore persiste dopo aver esaurito i tentativi, registra il campo request-id della risposta per la risoluzione dei problemi.

Errori di convalida

Gli errori di convalida indicano che un input di un'operazione non è stato accettato. Alcuni esempi sono PolicyViolationError, DateError, DateRangeError, StringLengthError e UrlFieldError.

Gli errori di convalida si verificano più comunemente nelle richieste avviate dall'utente, in cui un utente ha inserito un input non valido. In questi casi, devi fornire all'utente un messaggio di errore appropriato in base all'errore API specifico che hai ricevuto. Puoi anche convalidare l'input dell'utente per individuare errori comuni prima di effettuare una chiamata API, rendendo la tua app più reattiva e l'utilizzo dell'API più efficiente. Per le richieste dal backend, l'app potrebbe aggiungere l'operazione non riuscita a una coda per la revisione da parte di un operatore umano.

Molte app di Google Ads gestiscono un database locale per archiviare i propri oggetti Google Ads. Un problema di questo approccio è che il database locale potrebbe non essere sincronizzato con gli oggetti effettivi in Google Ads. Ad esempio, un utente potrebbe eliminare un gruppo di annunci direttamente in Google Ads, ma l'app e il database locale non sono a conoscenza della modifica e continuano a inviare chiamate API come se il gruppo di annunci esistesse. Questi problemi di sincronizzazione possono manifestarsi come una serie di errori, ad esempio DUPLICATE_CAMPAIGN_NAME, DUPLICATE_ADGROUP_NAME, AD_NOT_UNDER_ADGROUP, CANNOT_OPERATE_ON_REMOVED_ADGROUPAD e molti altri.

Per le richieste avviate dall'utente, una strategia consiste nell'avvisare l'utente di un possibile problema di sincronizzazione, avviare immediatamente un job che recupera la classe pertinente di oggetti Google Ads e aggiorna il database locale, quindi chiedere all'utente di aggiornare l'interfaccia utente.

Per le richieste di backend, alcuni errori forniscono informazioni sufficienti per consentire alla tua app di correggere automaticamente e in modo incrementale il database locale. Ad esempio, CANNOT_OPERATE_ON_REMOVED_ADGROUPAD dovrebbe fare in modo che la tua app contrassegni l'annuncio come rimosso nel database locale. Gli errori che non puoi gestire in questo modo potrebbero far sì che la tua app avvii un job di sincronizzazione più completo o venga aggiunta a una coda per la revisione da parte di un operatore umano.

Avanti
Informazioni sugli errori API