Limiti ed errori

Il piano Free ha anche un limite di 100 richieste al minuto per IP.

Come si contano

• Ogni richiesta conta uno, qualunque endpoint, anche quelle fatte dagli strumenti MCP. Anche la ricerca di fino a 50 aerei in una richiesta conta uno.
• I limiti sono per chiave: valgono le richieste di tutti i tuoi server e dispositivi insieme, da qualsiasi IP.
• Il piano Free ha anche un limite di 100 richieste al minuto per IP.
• Il contatore mensile riparte il primo del mese.
• Una richiesta respinta per un limite non viene contata, e non si paga nulla oltre il piano.
• Anche quanto indietro va lo storico voli dipende dal piano (tabella qui sopra). Una chiave Free con il vantaggio feeder ha i 30 giorni del Pro.
• Anche quanti aerei l’account può seguire per gli avvisi di decollo e atterraggio dipende dal piano (tabella qui sopra). Gestirli (/v2/watch) e gestire i webhook (/v2/webhooks) non conta: al massimo 20 chiamate al minuto per chiave.
• Dipendono dal piano anche le funzioni in più (tabella qui sopra): quanto indietro vanno le tracce, i sorvoli, le emergenze e gli aerei particolari, la pista in uso e quanti avvisi su un’area. Sorvoli, emergenze e pista partono da Starter. Una chiave Free con il vantaggio feeder ha le funzioni del Pro.

Ogni risposta riporta il tuo stato negli header:

Header	Valore
X-FIA-Plan	il piano della chiave (free, starter, pro, fleet, feeder)
X-FIA-Limit-Per-Min	richieste al minuto del piano
X-FIA-Quota-Month	richieste al mese del piano
X-FIA-Used-Month	quelle usate questo mese

Errori

Il corpo è sempre JSON con un campo error. Con 401, 403 e 429 c’è anche help, il link alla risposta nelle domande frequenti; il 403 dello storico voli ha invece docs e plans, e gli errori degli aerei seguiti hanno docs (e plans nel 403 di /v2/watch).

Codice	Quando	Cosa fare
400	parametri non validi (lat/lon/dist must be numeric, icao must be a 6-character hex address, date must be YYYY-MM-DD)	correggi la richiesta
400	un’opzione delle liste non valida: un nome sconosciuto in fields (con allowed e presets), un with diverso da route, più di 50 valori separati da virgole, un /box con i bordi fuori intervallo o nell’ordine sbagliato, since non in secondi Unix	correggi la richiesta; non viene contata
401	missing or invalid X-Api-Key	controlla header e chiave; una chiave rigenerata sostituisce la vecchia
403	raggio oltre il massimo del piano: c’è max_radius_km; anche un /box con la metà della diagonale oltre il massimo	riduci il raggio o il riquadro, dividi l’area in più richieste o passa a un piano superiore
403	code: "flights-depth": storico voli più indietro di quanto permette il piano, con max_days e requested_days	chiedi giorni più recenti, oppure scegli un piano che va più indietro
403	code: "plan-feature": una funzione che il piano non comprende, con feature (overflights, events, runways) e plan	scegli un piano che la comprende (tabella qui sopra); non viene contata
403	code: "tracks-depth": tracce più indietro di quanto permette il piano, con max_days e requested_days	chiedi un giorno più recente o scegli un piano con tracce più lunghe; non viene contata
403	code: "events-depth": emergenze e aerei particolari più indietro di quanto permette il piano, con max_hours e requested_hours	accorcia since o scegli un piano che va più indietro; non viene contata
400	code: "aircraft-invalid": un aereo in /v2/watch che non è un indirizzo ICAO, un’immatricolazione o un nominativo	correggilo; non si aggiunge niente della richiesta
403	code: "watch-plan-required": seguire aerei, o un avviso di decollo e atterraggio, con un piano senza aerei seguiti	scegli Fleet; elencare e togliere funzionano con ogni piano
409	code: "watch-limit": più aerei seguiti di quanti ne permette il piano, con max, count e adding	togline qualcuno prima, o scrivici per averne di più; non si aggiunge niente della richiesta
409	code: "area-webhook-limit": più avvisi su un’area di quanti ne permette il piano, con max_area	togline uno prima o scegli un piano con più avvisi
404	not found: l’aereo non è visto in questo momento; tried, hint e, quando c’è, last_seen dicono perché	controlla la forma del nominativo, oppure guarda il suo storico voli
429	troppe richieste al minuto (header Retry-After) o quota del mese finita (c’è resets)	aspetta Retry-After secondi; per la quota, il mese dopo o un piano superiore
503	servizio momentaneamente non disponibile; sulla pista in uso, runway data is not available yet finché i suoi dati non sono caricati	riprova con un’attesa crescente

Bloccato da Cloudflare

Se ricevi una pagina HTML invece del JSON (“Sorry, you have been blocked”, “Attention Required”, codice 1010 o 1020), la richiesta è stata fermata prima dell’API.

1. Manda sempre l’header X-Api-Key: le richieste a /v2/ senza chiave sono respinte a monte.
2. Usa un User-Agent tuo, per esempio il nome della tua app.
3. Se continua, scrivi a [email protected]. Indica l’ID CF-Ray in fondo alla pagina di errore, data e ora (UTC) e l’endpoint: con quelli troviamo la regola che ti ha fermato.