Descrizione dei codici di errore per le API di mappe spaziali sparse
Formato di risposta
Tutte le risposte API utilizzano un formato JSON unificato. Di seguito un esempio:
{
"statusCode": 119,
"msg": "Parameter has errors",
"date": "2022-06-15T09:56:30.000Z",
"result": //Il risultato viene ottenuto solo se statusCode è 0, se si verifica un errore, il campo risultato è vuoto.
}
| Campo | Tipo | Descrizione |
|---|---|---|
| statusCode | integer | Codice di stato operativo. 0 indica successo, non-zero indica errore |
| msg | string | Messaggio |
| result | object | Contenuto restituito. Quando lo statusCode è 0, restituisce la struttura dell'oggetto mappa target; altrimenti è vuoto |
| date | string | Orario del server |
[!Importante] Solo quando statusCode == 0, result include il contenuto della risposta. In altri stati, result è vuoto
Quando statusCode != 0, prestare attenzione al messaggio di errore msg
Classificazione dei codici di errore
Spiegazione dei codici di stato HTTP
| Codice di stato HTTP | Descrizione |
|---|---|
| 200 | Richiesta riuscita (può contenere errori operativi) |
| 400 | Errore nei parametri della richiesta |
| 401 | Autenticazione APIKey fallita |
| 403 | Permessi insufficienti o accesso alla risorsa vietato |
| 404 | Percorso URL dell'API richiesto non esistente |
| 500 | Errore interno del server |
| 502 | Eccezione dell'applicazione rilevata, possibile errore nei dati |
Nota: gli errori operativi vengono generalmente restituiti tramite risposta HTTP 200, identificati nel campo statusCode.
Tabella riepilogativa dei codici di stato operativi
| Status Code | Messaggio |
|---|---|
| 0 | Successo |
| 101 | Il file caricato è vuoto |
| 102 | Dimensione del file troppo grande |
| 106 | Parametro mancante o vuoto |
| 110 | Errori nella chiamata all'API del server |
| 111 | Risorsa non trovata |
| 401 | Token di autenticazione scaduto |
| 401 | Parametro di autenticazione mancante |
| 401 | appId o appKey sconosciuti |
| 401 | Account bloccato |
| 401 | Autenticazione fallita, firma o token non validi |
Scenari di errore comuni
Timeout senza risposta
- Request Timeout: rete lenta, si consiglia di verificare l'ambiente di rete del client
Errori relativi all'autenticazione
- Http 401 Unauthorized: autenticazione APIKey fallita, verificare la correttezza di appId/appKey
- Codice di stato 401: chiave applicazione non valida o applicazione inesistente, verificare la configurazione dell'applicazione
Errori nei parametri
- 400 Bad Request: formato dei parametri della richiesta errato
Errori nelle operazioni sulle risorse
- Codice di stato 10x: la risorsa target della query non esiste o parametri errati
Errori di sistema
- Http 50x Internal Server Error: eccezione interna del server o rilevamento di eccezione dell'applicazione, si consiglia di testare sul sito web o con un sample
Suggerimenti per le migliori pratiche
- Gestione client: si consiglia di determinare il successo operativo in base al campo
statusCode, non solo al codice di stato HTTP - Riprova in caso di errore: per errori 5xx è possibile riprovare, per errori 4xx verificare i parametri della richiesta
- Registrazione dei log: si consiglia di registrare la risposta di errore completa per facilitare la risoluzione dei problemi
- Gestione timeout: impostare un tempo di attesa ragionevole per evitare attese prolungate