Tipi di errore

Abbiamo suddiviso gli errori nelle seguenti categorie generali:

  • Autenticazione
  • Ripetibile
  • Convalida
  • Relativi alla sincronizzazione

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

  • Errori comuni fornisce maggiori dettagli su un errore specifico.
  • google.rpc.Status per i dettagli sul modello di errore logico utilizzato dall'API.
  • Codici di errore canonici per 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 potrebbe revocare l'accesso alla tua app in qualsiasi momento. A seconda del momento in cui l'accesso è stato revocato, 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 token revocato. 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 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 nell'indicare immediatamente un errore nell'interfaccia utente e dare all'utente la possibilità di attivare un nuovo tentativo. In alternativa, la tua app potrebbe prima riprovare automaticamente la richiesta, esponendo l'errore nell'interfaccia utente solo dopo aver raggiunto un numero massimo di tentativi o un tempo di attesa totale dell'utente.

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

Quando riprovi le richieste, utilizza una policy 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 tentativo 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 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 API specifico che hai ricevuto. Puoi anche convalidare l'input dell'utente per gli 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 back-end, 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 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 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 l'interfaccia utente.

Per le richieste di back-end, 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 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
Informazioni sugli errori API