Tipi di errore

Abbiamo suddiviso gli errori nelle seguenti categorie generali:

  • Autenticazione
  • Errori per i quali è possibile riprovare
  • Convalida
  • Relativi alla sincronizzazione

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

  • La sezione Errori comuni fornisce maggiori dettagli su un errore specifico.
  • 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 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 di 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 del momento in cui è 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.

Allo stesso modo, se il tuo progetto Google Cloud ha solo il livello di accesso 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 i quali è possibile riprovare

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 riprovare. 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 sul backend, l'app deve riprovare automaticamente la richiesta fino a un numero massimo di tentativi.

Quando riprovi a inviare le richieste, utilizza una policy di backoff esponenziale con jitter randomizzato. Ad esempio, se metti in pausa per 5 secondi prima del primo tentativo, potresti mettere in pausa per 10 secondi dopo il secondo tentativo e per 20 secondi dopo il terzo, aggiungendo un piccolo ritardo casuale a ogni intervallo per evitare picchi di tentativi sincronizzati. Il backoff esponenziale ti aiuta a non chiamare l'API in modo troppo aggressivo. Se un errore persiste dopo aver esaurito i tentativi, registra il request-id dalla risposta per la risoluzione dei problemi.

Errori di convalida

Gli errori di convalida indicano che un input di un'operazione non era accettabile. Esempi includono 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 umano.

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 deve far sì che la tua app contrassegni l'annuncio come rimosso nel database locale. Gli errori che non puoi gestire in questo modo potrebbero causare l'avvio di un'attività di sincronizzazione più completa per la tua app o l'aggiunta a una coda per la revisione da parte di un operatore umano.

Avanti
Informazioni sugli errori API