Gestione degli errori

Dopo aver effettuato una richiesta, potresti ricevere una risposta contenente dettagli sull'errore.

Riquadri 2D e immagini di Street View

L'elenco seguente descrive gli errori che potresti riscontrare quando utilizzi i riquadri 2D e le immagini di Street View.

Elenco di errori

Il seguente elenco descrive gli errori che potresti riscontrare durante l'utilizzo dell'API Map Tiles.

required
Nella richiesta manca un parametro URL. Tieni presente che il messaggio di errore indica quale parametro è mancante.
notFound, invalid

I valori x, y o z sono fuori intervallo.

  • Per i riquadri della mappa standard, il livello di zoom massimo dipende dal riquadro della mappa specifico e dalle opzioni della mappa che hai richiesto.

  • Per i normali riquadri della mappa, la coordinata x deve rientrare nell'intervallo [0, (2^zoom)-1].

  • Per i riquadri della mappa standard, la coordinata y deve rientrare nell'intervallo [0, (2^(zoom-1))-1].

  • Per le schede di Street View, lo zoom deve essere compreso tra zero e cinque, inclusi.

  • Per i riquadri di Street View, gli intervalli di coordinate x e y sono gli stessi per i riquadri delle mappe standard, fino al livello di zoom 5. A quel punto, i valori massimi sono imageHeight o imagewidth diviso per tileHeight o tileWidth.

forbidden: Nella richiesta manca una chiave API valida.

expired
Il token session è scaduto. Un token di sessione è valido per due settimane dal momento della creazione. Tieni presente che potrebbe cambiare senza preavviso. Se ricevi questo errore, devi ottenere un nuovo token di sessione, come descritto in Utilizzare i token di sessione.
badRequest

La tua richiesta non era valida. I motivi più comuni sono:

  • Hai specificato un tipo di mappa terrain senza includere un livello roadmap.

  • Hai incluso un array styles per un tipo di mappa diverso da quello della roadmap.

  • Hai inviato un valore lat/lng e un ID panorama in una richiesta di metadati di Street View.

quotaExceeded, rateLimitExceeded

La tua applicazione ha superato la quota consentita o il numero consentito di query al secondo.

Errore di esempio

{
  "error": {
    "code": 403,
    "message": "The request is missing a valid API key.",
    "errors": [
      {
        "message": "The request is missing a valid API key.",
        "domain": "global",
        "reason": "forbidden"
      }
    ],
    "status": "PERMISSION_DENIED"
  }
}

Riprova delle richieste

Quando le richieste non vanno a buon fine con quotaExceeded e rateLimitExceeded, devi ritentare in modo che le richieste non valide o gli errori su larga scala non inondino i server di Google, poiché molti client tentano di ripetere le richieste in rapida successione. Ciò significa utilizzare il backoff esponenziale quando riprovi a inviare le richieste. Il backoff esponenziale ti obbliga a distribuire le richieste nel tempo per dare al server il tempo di riprendersi.

Ad esempio, se una richiesta non va a buon fine, riprova dopo un secondo. Se anche questo tentativo non va a buon fine, riprova a inviare la richiesta dopo due secondi. Se anche questa richiesta non va a buon fine, riprova dopo quattro secondi. In questo modo, puoi suddividere efficacemente ogni richiesta successiva semplicemente raddoppiando il periodo di tempo che le separa.

Riquadri 3D

Gli errori del server di Google potrebbero non essere evidenti perché accedi ai riquadri fotorealistici tramite un renderer, responsabile della gestione degli errori del server.

Errori del visualizzatore di riquadri

Ad esempio, il renderer CesiumJS in genere non va a buon fine in silenzio quando si verificano errori del server, il che può comportare arresti anomali, schermate vuote o il mancato caricamento di riquadri specifici.

La tecnica utilizzata per eseguire il debug degli errori del server dipenderà dal renderer specifico utilizzato. Per i renderer basati su browser come CesiumJS, puoi esaminare il traffico di rete con gli strumenti integrati nella maggior parte dei browser. Ad esempio, puoi utilizzare Chrome DevTools.

Errori comuni

L'elenco seguente contiene i dettagli degli errori più comuni che potresti riscontrare.

400: argomento non valido
Chiavi API, parametri di query, ID riquadri/set di riquadri non validi o un token di sessione scaduto.
403: autorizzazione negata
Chiave API mancante, connessione SSL mancante o la chiave API non è stata aggiunta alla lista consentita per le tessere 3D. Contatta l'Assistenza Google fornendo il tuo ID progetto per farti aggiungere alla lista consentita per la funzionalità 3D Tiles dell'API Map Tiles.
429: troppe richieste
La tua quota è esaurita. Contatta l'Assistenza Google per aumentare la quota.