Tipi di errore

Abbiamo classificato gli errori nelle seguenti categorie generali:

  • Autenticazione
  • Riprovabile
  • Convalida
  • Relativi alla sincronizzazione

Sebbene queste categorie non comprendano tutti gli errori possibili e alcune possano rientrare in più di una categoria, possono comunque essere utili come punto di partenza per strutturare la gestione degli errori dell'app. Per ulteriori dettagli su errori specifici, consulta le seguenti risorse:

Errori di autenticazione

L'autenticazione indica se un utente ha concesso alla tua app l'autorizzazione 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 si verifica un errore di autenticazione da fattori non soggetti al tuo controllo è che l'utente autenticato ha revocato l'autorizzazione che ha concesso alla tua app di agire per suo conto. Ad esempio, se la tua app gestisce account Google Ads distinti per clienti indipendenti e si autentica separatamente come ciascun cliente quando gestisce l'account del cliente, un cliente potrebbe revocare l'accesso della tua app in qualsiasi momento. A seconda di quando è stato revocato il tuo 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 clienti, potrebbe chiedergli di riavviare il flusso OAuth2 per ristabilire l'autorizzazione dell'app a operare per loro conto.

Errori non irreversibili

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 è indicare immediatamente un errore nella UI e offrire all'utente la possibilità di attivare un nuovo tentativo. In alternativa, la tua app potrebbe prima riprovare automaticamente la richiesta, mostrando l'errore nell'interfaccia utente solo dopo aver raggiunto un numero massimo di tentativi o il tempo di attesa totale dell'utente.

Per le richieste avviate sul back-end, l'app deve riprovare automaticamente fino a un numero massimo di tentativi.

Quando riprovi a inviare le richieste, utilizza un criterio di backoff esponenziale. Ad esempio, se la prima volta metti in pausa 5 secondi prima del primo tentativo, puoi mettere in pausa 10 secondi dopo il secondo e 20 secondi dopo il terzo tentativo. Il backoff esponenziale consente di verificare che l'API non venga chiamata in modo troppo aggressivo.

Errori di convalida

Gli errori di convalida indicano che un input per un'operazione non è stato accettato. Ad esempio, 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 un messaggio di errore appropriato all'utente in base all'errore API specifico che hai ricevuto. Puoi anche verificare se gli input degli utenti contengono errori comuni prima di effettuare una chiamata all'API, rendendo la tua app più reattiva e l'utilizzo dell'API più efficiente. Per le richieste provenienti dal back-end, l'app potrebbe aggiungere l'operazione non riuscita a una coda per la revisione da parte di un operatore umano.

Molte app Google Ads gestiscono un database locale per archiviare i propri oggetti Google Ads. Uno dei problemi di questo approccio è che il database locale potrebbe non essere più 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 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 degli 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 all'app di correggere automaticamente e in modo incrementale il database locale. Ad esempio, CANNOT_OPERATE_ON_REMOVED_ADGROUPAD dovrebbe indurre l'app a contrassegnare l'annuncio come rimosso nel database locale. Gli errori che non puoi gestire in questo modo potrebbero causare l'avvio di un job di sincronizzazione più completo nella tua app o essere aggiunti a una coda per la revisione da parte di un operatore umano.

Indietro
Account di prova
Avanti
Errori comuni