Gestire gli errori dell'API

Quando invii una richiesta all'API Google Ads, la richiesta potrebbe non riuscire per vari motivi. Ad esempio, potresti fornire un argomento non valido o il tuo account potrebbe aver raggiunto il limite per la creazione di nuove campagne. In questi casi, l'API restituisce un errore per comunicarti cosa non ha funzionato.

Questa guida spiega come leggere e gestire gli errori API per creare applicazioni più robuste.

Struttura dell'errore

Se utilizzi una delle nostre librerie client, gli errori API vengono visualizzati come eccezioni. Queste eccezioni contengono dettagli che ti aiutano a capire perché si è verificato l'errore.

L'API Google Ads restituisce informazioni sugli errori in un formato standard. Se si verifica un errore, la risposta conterrà un oggetto GoogleAdsFailure. Questo oggetto contiene un elenco di singoli oggetti GoogleAdsError, ognuno dei quali descrive un errore specifico.

Ogni oggetto GoogleAdsError fornisce:

• error_code: un codice di errore specifico che indica il tipo di errore, ad esempio AuthenticationError.NOT_ADS_USER.
• message: una descrizione leggibile del motivo per cui si è verificato l'errore.
• trigger: il valore che ha causato l'errore, ad esempio "1234".
• location: dettagli sulla parte della richiesta che ha causato l'errore, ad esempio un nome di campo specifico.

Oltre all'elenco degli errori, GoogleAdsFailure contiene un requestId, ovvero un identificatore univoco per la richiesta API che ha generato un errore.

Errore di esempio

Ecco un esempio di come appare un errore in formato JSON. Questo errore indica che il campo name di ad_group all'indice 0 non è presente nella richiesta.

{
  "code": 3,
  "message": "Request contains an invalid argument.",
  "details": [
    {
      "@type": "type.googleapis.com/google.ads.googleads.v22.errors.GoogleAdsFailure",
      "errors": [
        {
          "errorCode": {
            "requestError": "REQUIRED_FIELD_MISSING"
          },
          "message": "Required field is missing",
          "location": {
            "fieldPathElements": [
              {
                "fieldName": "ad_group",
                "index": 0
              },
              {
                "fieldName": "name"
              }
            ]
          }
        }
      ],
      "requestId": "unique_request_id_12345"
    }
  ]
}

Come gestire gli errori

Se si verifica un errore, ecco i passaggi da seguire:

1. Esamina l'elenco errors: guarda ogni GoogleAdsError nell'oggetto GoogleAdsFailure. error_code e message ti diranno cosa non ha funzionato.
2. Controlla il campo location: il campo location può aiutarti a individuare in quale punto della richiesta si è verificato il problema.
3. Consulta la documentazione: per codici di errore specifici, consulta la pagina degli errori comuni o il riferimento completo ai codici di errore per maggiori dettagli sull'errore e su come correggerlo.
4. Modifica la richiesta: in base al messaggio di errore, correggi la richiesta API. Ad esempio, se vedi REQUIRED_FIELD_MISSING, assicurati di fornire questo campo nella richiesta.
5. Registra request_id: se non riesci a capire come risolvere un errore e devi contattare l'assistenza tramite il forum, includi request_id. Questo ID aiuta i tecnici di Google a esaminare il problema.

Passaggi successivi

• Consulta la sezione Errori comuni per un elenco dei problemi frequenti e delle relative soluzioni.
• Per tecniche di gestione degli errori più avanzate, tra cui la logica di ripetizione e l'errore parziale, consulta Informazioni sugli errori dell'API.