Documentazione errori

Codici di errore

Ogni errore usa lo stesso formato: { error, code, request_id, doc_url, retry_after? }. request_id permette di ritrovare la richiesta nel supporto; doc_url porta alla pagina di questo codice. Il catalogo è scaricabile anche come JSON.

missing_tokenHTTP 401

Chiave mancante

Causa: La richiesta non ha l'header Authorization.

Soluzione: Aggiungi "Authorization: Bearer gk_live_..." (o la chiave demo_) a ogni richiesta.

invalid_tokenHTTP 401

Chiave non valida o revocata

Causa: La chiave non esiste, è stata revocata, oppure il token è stato troncato/copiato male.

Soluzione: Verifica la chiave nel portale; se revocata, creane una nuova.

forbiddenHTTP 403

Privilegi insufficienti

Causa: Endpoint admin chiamato con una chiave senza privilegi admin.

Soluzione: Usa la chiave admin di sistema per le operazioni di gestione.

bad_requestHTTP 400

Parametri non validi

Causa: Parametri mancanti (nessun address/code/lat+lon) o valori fuori range.

Soluzione: Controlla i parametri nella risposta e nella specifica OpenAPI.

address_not_foundHTTP 404

Indirizzo non trovato

Causa: Nessun indirizzo corrisponde; in modalità strict anche quando il civico non esiste o manca.

Soluzione: Usa l'autocomplete per suggerimenti reali e invia il code; oppure rimuovi strict=1 e leggi notice.

not_foundHTTP 404

Endpoint inesistente

Causa: Percorso URL sbagliato.

Soluzione: Verifica il percorso nella specifica (es. /coverage/italy, senza /v1).

rate_limit_exceededHTTP 429

Frequenza superata

Causa: Più richieste del limite al minuto (rpm) consentito; il burst è ~5 secondi di margine.

Soluzione: Rispetta retry_after (o l'header Retry-After) prima di ritentare. Il campo usage/credits mostra i limiti.

daily_quota_exceededHTTP 429

Quota giornaliera esaurita

Causa: Superato il tetto giornaliero del piano.

Soluzione: Attendi il reset UTC di mezzanotte o passa a un piano superiore.

monthly_quota_exceededHTTP 429

Quota mensile esaurita

Causa: Superato il tetto mensile del piano.

Soluzione: Attendi il reset mensile o passa a un piano superiore.

credits_rate_limitedHTTP 429

Endpoint /credits limitato

Causa: Il controllo crediti è limitato a 1 richiesta al secondo per account.

Soluzione: Metti in cache il risultato di /credits invece di chiamarlo a ogni richiesta.

coverage_unavailableHTTP 503

Database di copertura non disponibile

Causa: Il servizio sta aggiornando i dati (refresh mensile) o è in manutenzione.

Soluzione: Riprova tra qualche minuto; durante il refresh il servizio resta in linea quasi sempre.

streets_unavailableHTTP 503

Indice strade non disponibile

Causa: Indice ANNCSU in fase di rebuild.

Soluzione: Riprova tra qualche minuto.

internalHTTP 500

Errore interno

Causa: Errore inatteso del servizio.

Soluzione: Riprova; se persiste, apri un ticket citando il campo request_id della risposta.

Per testare ogni stato prima di andare in produzione usa le chiavi demo deterministiche (demo_404, demo_429…).