Tipi di errore

Abbiamo suddiviso gli errori nelle seguenti categorie generali:

  • Autenticazione
  • Retryable
  • Convalida
  • Relativi alla sincronizzazione

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

  • La sezione Errori comuni fornisce maggiori dettagli su un errore specifico.
  • google.rpc.Status per i dettagli sul modello di errore logico utilizzato dall'API.

Errori di autenticazione

L'autenticazione si riferisce al fatto che un utente abbia 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 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 e si autentica separatamente come ogni cliente quando gestisce l'account di quel cliente, un cliente può revocare l'accesso alla 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 integrate nelle librerie client potrebbero generare un'eccezione di revoca del token. 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.

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 consiste nell'indicare immediatamente un errore nell'interfaccia utente 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 un tempo di attesa totale per l'utente.

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

Quando riprovi a inviare le richieste, utilizza un criterio di backoff esponenziale. Ad esempio, se metti in pausa per 5 secondi prima del primo tentativo, potresti mettere in pausa per 10 secondi dopo il secondo e per 20 secondi dopo il terzo tentativo. Il backoff esponenziale ti aiuta a non chiamare l'API in modo troppo aggressivo.

Errori di convalida

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

Gli errori di convalida si verificano più comunemente nelle richieste avviate dagli utenti, 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 convalidare l'input dell'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 da parte di un operatore.

Molte app Google Ads gestiscono un database locale per archiviare i propri oggetti Google Ads. Una sfida 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 effettuare 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 la UI.

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 far sì 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.

Avanti
Errori comuni