Errori API e soluzioni

An API key is required for all endpoints. Get a free key at https://app.zornade.com/api

Causa: La richiesta non include il header x-api-key.

Soluzione: Aggiungi il header x-api-key con un token creato su app.zornade.com/api. L'unico endpoint pubblico è /api/v2/health.

Invalid or expired API key.

Causa: Il token non esiste, è stato revocato oppure è scaduto.

Soluzione: Controlla di aver copiato il token completo (inizia con zrn_) e che non sia scaduto o revocato nella lista token.

Too many failed authentication attempts. Try again later.

Causa: Troppi tentativi di autenticazione falliti dallo stesso indirizzo IP.

Soluzione: Attendi il periodo indicato nel campo retry_after_seconds (900 secondi) e verifica il token prima di riprovare.

Rate limit exceeded: 10000 requests/hour. Try again later.

Causa: Il token ha superato le 10.000 richieste nell'ora corrente.

Soluzione: Attendi il reset orario (header X-RateLimit-Reset) oppure distribuisci il carico tra più token, fino a 5 per utente.

Coordinates must be within Italy.

Causa: Le coordinate inviate sono fuori dall'area italiana coperta.

Soluzione: Usa coordinate italiane: latitudine 35.5-47.5, longitudine 6.0-19.0.

Es. "comune is required", "bbox format: minLng,minLat,maxLng,maxLat", "points format: lat1,lng1;lat2,lng2 (max 10 points)."

Causa: Parametri mancanti o nel formato sbagliato.

Soluzione: Controlla la firma dell'endpoint nella documentazione: comune obbligatorio in parcels/search, bbox e points separati da virgole e punto e virgola.

Bounding box too large. Max span: 0.05° per side (~5.5 km).

Causa: Il bounding box supera l'estensione massima di 0.05 gradi per lato.

Soluzione: Dividi l'area in più richieste bbox più piccole oppure usa la modalità multi-punto.

This endpoint requires the "<scope>" scope. Your token has: [...]

Causa: Il token non ha lo scope richiesto dall'endpoint (parcels:read, geocoding:read o admin_data:read).

Soluzione: Crea un nuovo token con lo scope mancante oppure rigenera il token esistente con gli scopes corretti.

Parcel "<id>" not found.

Causa: Il fid o gml_id richiesto non esiste nel dataset.

Soluzione: Verifica l'id con una ricerca per comune o coordinate, poi ripeti la richiesta di dettaglio.

Messaggio dell'errore interno del database.

Causa: Errore temporaneo nella risoluzione della query lato server.

Soluzione: Riprova dopo qualche secondo. Se l'errore persiste, segnala il messaggio completo al supporto.