Risposte di errore

Risposte di errore standard

Se una richiesta API Metadata ha esito positivo, l'API restituisce un codice di stato 200. Se si verifica un errore con una richiesta, l'API restituisce un codice di stato HTTP, uno stato e un motivo nella risposta in base al tipo di errore. Inoltre, il corpo della risposta contiene una descrizione dettagliata di ciò che ha causato l'errore. Ecco un esempio di risposta di errore:

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "invalidParameter",
    "message": "Invalid value '-1' for max-results. Value must be within the range: [1, 1000]",
    "locationType": "parameter",
    "location": "max-results"
   }
  ],
  "code": 400,
  "message": "Invalid value '-1' for max-results. Value must be within the range: [1, 1000]"
 }
}

Tabella degli errori

Codice Motivo Descrizione Azione consigliata
400 invalidParameter Indica che un parametro di richiesta contiene un valore non valido. I campi locationType e location nella risposta di errore forniscono informazioni sul valore non valido. Non riprovare senza aver risolto il problema. Devi fornire un valore valido per il parametro specificato nella risposta di errore.
400 badRequest Indica che la query non è valida. Ad esempio, manca l'ID principale oppure la combinazione di dimensioni o metriche richieste non è valida. Non riprovare senza aver risolto il problema. Devi apportare modifiche alla query API affinché funzioni.
401 invalidCredentials Indica che il token di autenticazione non è valido o è scaduto. Non riprovare senza aver risolto il problema. Devi ottenere un nuovo token di autenticazione.
403 insufficientPermissions Indica che l'utente non dispone di autorizzazioni sufficienti per l'entità specificata nella query. Non riprovare senza aver risolto il problema. Devi disporre di autorizzazioni sufficienti per eseguire l'operazione sull'entità specificata.
403 dailyLimitExceeded Indica che l'utente ha superato la quota giornaliera (per progetto o per vista (profilo)). Non riprovare senza aver risolto il problema. Hai esaurito la quota giornaliera. Consulta Limiti e quote dell'API.
403 userRateLimitExceeded Indica che il limite di query per 100 secondi per utente è stato superato. Il valore predefinito impostato nella console API di Google è 100 query ogni 100 secondi per utente. Puoi aumentare questo limite nella console API di Google fino a un massimo di 1000. Riprova utilizzando il backoff esponenziale. Devi rallentare la velocità di invio delle richieste.
403 rateLimitExceeded Indica che sono stati superati i limiti di frequenza di query per 100 secondi del progetto. Riprova utilizzando il backoff esponenziale. Devi rallentare la velocità di invio delle richieste.
403 quotaExceeded Indica che sono state raggiunte le 10 richieste in parallelo per vista (profilo) nell'API di reporting principale. Riprova utilizzando il backoff esponenziale. Devi attendere il completamento di almeno una richiesta in corso per questa visualizzazione (profilo).
500 internalServerError Si è verificato un errore interno imprevisto del server. Non riprovare a eseguire questa query più di una volta.
503 backendError Il server ha restituito un errore. Non riprovare a eseguire questa query più di una volta.

Gestione di 500 o 503 risposte

Un errore 500 o 503 potrebbe verificarsi in caso di carico elevato o in caso di richieste più complesse e di grandi dimensioni. Per le richieste più grandi, valuta la possibilità di richiedere dati per un periodo di tempo più breve. Inoltre, valuta la possibilità di implementare il backoff esponenziale. La frequenza di questi errori può dipendere dalla vista (profilo) e dalla quantità di dati dei report associati alla vista in questione. Una query che causa un errore 500 o 503 per una vista (profilo) non genera necessariamente un errore per la stessa query con una vista (profilo) diversa.

Implementazione del backoff esponenziale

Il backoff esponenziale è il processo con cui un client riprova periodicamente a una richiesta non riuscita in un periodo di tempo crescente. È una strategia standard di gestione degli errori per le applicazioni di rete. L'API Metadata è progettata in modo che i client che scelgono di ritentare le richieste non riuscite lo facciano utilizzando un backoff esponenziale. Oltre a essere "obbligatorio", l'utilizzo del backoff esponenziale aumenta l'efficienza dell'utilizzo della larghezza di banda, riduce il numero di richieste necessarie per ottenere una risposta di successo e ottimizza la velocità effettiva delle richieste in ambienti simultanei.

Il flusso per l'implementazione di un backoff esponenziale semplice è il seguente.

  1. invia una richiesta all'API
  2. Ricevi una risposta di errore con un codice di errore riprovabile
  3. Attendi 1 s + random_number_milliseconds secondi
  4. Riprova la richiesta
  5. Ricevi una risposta di errore con un codice di errore riprovabile
  6. Attendi 2 s + random_number_milliseconds secondi
  7. Riprova la richiesta
  8. Ricevi una risposta di errore con un codice di errore riprovabile
  9. Attendi 4 sec + random_number_milliseconds secondi
  10. Riprova la richiesta
  11. Ricevi una risposta di errore con un codice di errore riprovabile
  12. Attendi 8 sec + random_number_milliseconds secondi
  13. Riprova la richiesta
  14. Ricevi una risposta di errore con un codice di errore riprovabile
  15. Attendi 16 sec + random_number_milliseconds secondi
  16. Riprova la richiesta
  17. Se l'errore persiste, interrompi e registra l'errore.

Nel flusso precedente, random_number_milliseconds è un numero casuale di millisecondi inferiore o uguale a 1000. Questa operazione è necessaria per evitare determinati errori di blocco in alcune implementazioni simultanee. random_number_milliseconds deve essere ridefinito dopo ogni attesa.

Nota: l'attesa è sempre (2 ^ n) + random_number_milliseconds, dove n è un numero intero crescente monotonico inizialmente definito come 0. n viene incrementato di 1 per ogni iterazione (ogni richiesta).

L'algoritmo è impostato per terminare quando n è 5. Questo limite serve solo a impedire ai client di riprovare all'infinito e genera un ritardo totale di circa 32 secondi prima che una richiesta venga considerata "un errore irreversibile".

Il seguente codice Python è un'implementazione del flusso precedente per il ripristino da errori che si verificano in un metodo chiamato makeRequest.

import random
import time
from apiclient.errors import HttpError

def makeRequestWithExponentialBackoff(analytics):
  """Wrapper to request Google Analytics data with exponential backoff.

  The makeRequest method accepts the analytics service object, makes API
  requests and returns the response. If any error occurs, the makeRequest
  method is retried using exponential backoff.

  Args:
    analytics: The analytics service object

  Returns:
    The API response from the makeRequest method.
  """
  for n in range(0, 5):
    try:
      return makeRequest(analytics)

    except HttpError, error:
      if error.resp.reason in ['userRateLimitExceeded', 'quotaExceeded',
                               'internalServerError', 'backendError']:
        time.sleep((2 ** n) + random.random())
      else:
        break

  print "There has been an error, the request never succeeded."