Tipi di errore

Abbiamo classificato gli errori nelle seguenti categorie generali:

• Autenticazione
• Riprovabile
• Convalida
• Correlati alla sincronizzazione

Anche se queste categorie non comprendono tutti gli errori possibili e alcune possono rientrare in più di una categoria, possono comunque servire da punto di partenza per strutturare la gestione degli errori dell'app. Consulta la sezione Errori comuni per ulteriori dettagli su un determinato errore.

Errori di autenticazione

Per autenticazione si intende se alla tua app è stata concessa o meno l'autorizzazione di un utente ad accedere a Google Ads per suo conto. L'autenticazione viene gestita tramite credenziali generate dal flusso OAuth2.

Il motivo più comune per cui un errore di autenticazione deriva da fattori che esulano dal tuo controllo è che l'utente autenticato abbia revocato l'autorizzazione che ha concesso alla tua app di agire per suo conto. Ad esempio, se la tua app gestisce account Google Ads separati per client indipendenti e autentica separatamente come ogni client quando gestisce l'account di quel client, quest'ultimo può revocare l'accesso all'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 integrate nelle librerie client potrebbero generare un'eccezione relativa alla revoca del token. In ogni caso, se la tua app ha una UI per i tuoi clienti, potrebbe chiedere loro di riavviare il flusso OAuth2 per ristabilire l'autorizzazione dell'app ad agire per loro conto.

Errori ripetibili

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

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

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

Quando esegui di nuovo le richieste, utilizza un criterio di backoff esponenziale. Ad esempio, se ti metti in pausa 5 secondi prima del primo tentativo, puoi fermarti 10 secondi dopo il secondo e 20 secondi dopo il terzo tentativo. Il backoff esponenziale aiuta ad assicurare di non chiamare l'API in modo troppo aggressivo.

Errori di convalida

Gli errori di convalida indicano che un input per un'operazione non era accettabile. Ad esempio, PolicyViolationError, DateError, DateRangeError, StringLengthError e UrlFieldError.

Gli errori di convalida si verificano più spesso nelle richieste avviate dall'utente, in cui un utente ha inserito input non validi. In questi casi, devi fornire all'utente un messaggio di errore appropriato in base all'errore specifico dell'API che hai ricevuto. Puoi anche convalidare l'input utente per 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, la tua app potrebbe aggiungere l'operazione non riuscita a una coda per la revisione di un operatore umano.

Errori relativi alla sincronizzazione

Molte app di Google Ads gestiscono un database locale in cui archiviare gli oggetti di 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 emettere chiamate API come se il gruppo di annunci esistesse. Questi problemi di sincronizzazione possono manifestarsi come vari 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 aggiornare il database locale, poi richiedere all'utente di aggiornare l'interfaccia utente.

Per le richieste back-end, alcuni errori forniscono informazioni sufficienti affinché l'app possa 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 tuo 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.