Abbiamo classificato gli errori nelle seguenti grandi categorie:
- Autenticazione
- Riprova
- Dati di
- Correlato alla sincronizzazione
Queste categorie non includono tutti i possibili errori, ma alcune possono rientrare in più di una categoria, ma possono comunque fungere da punto di partenza per strutturare la gestione degli errori dell'app. Per ulteriori dettagli su un determinato errore, consulta la sezione Errori comuni.
Errori di autenticazione
L'autenticazione indica se un utente ha autorizzato la tua app ad accedere a Google Ads per suo conto. L'autenticazione viene gestita tramite le credenziali generate dal flusso OAuth2.
Il motivo più comune per cui un errore di autenticazione deriva da fattori fuori dal 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 client indipendenti e si autentica separatamente come ciascun client durante la gestione dell'account di quel cliente, un client potrebbe revocare l'accesso della tua app in qualsiasi momento. A seconda di quando l'accesso è stato revocato, l'API potrebbe restituire direttamente un errore AuthenticationError.OAUTH_TOKEN_REVOKED oppure gli oggetti delle credenziali integrati nelle librerie client potrebbero generare un'eccezione revocata per il token. In ogni caso, se la tua app ha una UI per i 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 a inviare la
richiesta dopo una breve pausa.
Per le richieste avviate dall'utente, una strategia consiste nell'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 la richiesta, mostrando l'errore nell'interfaccia utente solo dopo aver raggiunto il numero massimo di nuovi tentativi o il tempo di attesa totale utente.
Per le richieste avviate dal backend, la tua app dovrebbe ritentare automaticamente la richiesta fino a un numero massimo di nuovi tentativi.
Quando riprovi le richieste, utilizza un criterio di backoff esponenziale. Ad esempio, se ti interrompi per la prima volta 5 secondi prima del primo tentativo, potresti farlo 10 secondi dopo il secondo e 20 secondi dopo il terzo. Il backoff esponenziale serve a evitare di 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 un input non valido. 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 l'app più reattiva e l'uso dell'API più efficiente. Per le richieste dal backend, la tua app potrebbe aggiungere l'operazione non riuscita a una coda per la revisione da parte di un operatore umano.
Errori relativi alla sincronizzazione
Molte app Google Ads gestiscono un database locale per archiviare gli oggetti Google Ads. Un problema di questo approccio è che il database locale potrebbe non essere sincronizzato con gli oggetti effettivi di 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 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 è 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, quindi chiede all'utente di aggiornare l'interfaccia utente.
Per le richieste di backend, alcuni errori forniscono informazioni sufficienti all'app per correggere automaticamente e in modo incrementale il database locale. Ad esempio, CANNOT_OPERATE_ON_REMOVED_ADGROUPAD deve far sì che l'app contrassegni l'annuncio come rimosso nel database locale. Gli errori che non puoi gestire in questo modo potrebbero far sì che l'app avvii un job di sincronizzazione più completo o vengano aggiunti a una coda per la revisione da parte di un operatore umano.