Errori e limiti

Forma delle risposte

Ogni risposta v2 ha la stessa busta:

{
  "data": { },
  "meta": { "pagination": { "limit": 50, "offset": 0, "count": 12 } }
}

meta.pagination compare solo sugli elenchi.

Errori

Gli errori v2 hanno un codice stabile su cui puoi scrivere del codice — fai lo switch su error.code, mai sul testo di error.message, che può cambiare:

{ "error": { "code": "DEVICE_NOT_FOUND", "message": "Dispositivo non trovato." } }

HTTP	error.code	Significato
400	IMEI_REQUIRED	IMEI mancante nel percorso
400	BAD_REQUEST	Parametri non validi (es. range storico troppo ampio, from/to non ISO-8601)
400	COORDINATES_REQUIRED	lat/lng mancanti su /devices/nearest
400	INVALID_COORDINATES	lat/lng fuori range o non numerici
403	API_KEY_REQUIRED	Autenticato ma non con API key (es. sessione web), o key assente
403	(testo libero)	Permesso/scope mancante sulla chiave — {"error": "API key senza permesso: <permesso>"}
403	FORBIDDEN	Permesso specifico mancante (es. comandi non abilitati per un sotto-account)
404	DEVICE_NOT_FOUND	Dispositivo inesistente o fuori dallo scope della chiave — le due situazioni non si distinguono, per non rivelare l’esistenza di un IMEI che non è tuo
404	LOCATION_NOT_FOUND	Il dispositivo non ha ancora inviato una posizione
429	(nessun code dedicato)	Rate limit superato
500	INTERNAL_ERROR	Errore nostro

Autenticazione fuori dalla busta v2

Le richieste rifiutate prima di entrare nel router v2 (API key sconosciuta, revocata, IP bloccato) usano i codici dell’autenticazione generale — API_KEY_INVALID, API_KEY_REVOKED, API_KEY_OWNER_INACTIVE, API_KEY_IP_BLOCKED — con lo stesso schema {"message", "code"}. Non sono elencati sopra perché non appartengono alla busta {"error": {...}} di v2, ma restano 403.

Rate limiting

Limite	Valore
Per chiave, al minuto	120
Per chiave, all’ora	1000
Per indirizzo IP, al minuto	120

Oltre il limite: 429. Nessun header X-RateLimit-* né Retry-After nelle risposte: regola il tuo client sui numeri sopra, non su un header che non esiste.

Paginazione

Parametro	Default	Range
limit	varia per endpoint (50 o 500 a seconda della risorsa)	vedi la pagina della risorsa
offset	0	≥ 0

I valori fuori range vengono clampati, non rifiutati: limit=99999 diventa il massimo consentito per quell’endpoint, non un errore. meta.pagination.count è il numero di elementi nella pagina corrente, non il totale della risorsa.