---
title: "Limits and errors"
description: "API limits per plan (per minute, per month, radius, how far back the flight history goes), how they're counted, the X-FIA-* headers, and what to do about 400-429 errors and Cloudflare blocks."
url: https://flyitalyadsb.com/data/api/docs/limits-and-errors.md
page_for_people: https://flyitalyadsb.com/data/api/docs/limits-and-errors/
language: en
generated: 2026-11-09
license: CC BY-SA 4.0 (data)
---

# Limits and errors

> API limits per plan (per minute, per month, radius, how far back the flight history goes), how they're counted, the X-FIA-* headers, and what to do about 400-429 errors and Cloudflare blocks.

| Plan | Price per month (before tax) | Requests per minute | Requests per month | Maximum radius | Flight history (how far back) | Tracks (how far back) | Overflights (per request) | Emergencies and notable aircraft | Runway in use | Area alerts | Watched aircraft | Commercial use |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Free | €0 | 30 | 300,000 | 500 km | 7 days | 7 days | — | — | — | — | — | yes |
| Starter | €9 | 60 | 1,000,000 | 1,000 km | 14 days | 30 days | 10 km, 6 h | last 24 h | yes | 1 | — | yes |
| Pro | €49 | 300 | 10,000,000 | whole world | 30 days | 90 days | 50 km, 24 h | 7 days | yes | 5 | — | yes |
| Fleet | €149 | 300 | 10,000,000 | whole world | 90 days | since 2022 | 50 km, 24 h | 7 days | yes | 5 | 25 | yes |

Prices per month, before tax.

## How requests count

- **Every request counts as one**, whatever the endpoint, including those made by MCP tools. A lookup of up to 50 aircraft in [one request](https://flyitalyadsb.com/data/api/docs/endpoints.md#several-aircraft-in-one-request) counts as one too.
- Limits are **per key**: requests from all your servers and devices count together, from any IP.
- The Free plan also has a limit of 100 requests per minute per IP.
- **The monthly counter resets on the 1st.**
- A request refused for a limit is not counted, and nothing is billed beyond the plan.
- How far back the [flight history](https://flyitalyadsb.com/data/api/docs/endpoints.md#observed-flights-depth) go depends on the plan too (table above). A Free key with the feeder perk gets Pro's 30 days.
- How many aircraft the account can [watch](https://flyitalyadsb.com/data/api/docs/alerts.md#aircraft) for takeoff and landing alerts depends on the plan too (table above). Managing them (`/v2/watch`) and the webhooks (`/v2/webhooks`) is not counted: at most 20 calls a minute per key.
- The extras depend on the plan too (table above): how far back the [tracks](https://flyitalyadsb.com/data/api/docs/history.md) go, [overflights](https://flyitalyadsb.com/data/api/docs/history.md#what-flew-over-a-place), [emergencies and notable aircraft](https://flyitalyadsb.com/data/api/docs/alerts.md#emergencies-and-notable-aircraft-v2events), the [runway in use](https://flyitalyadsb.com/data/api/docs/endpoints.md#runway-in-use) and how many [area alerts](https://flyitalyadsb.com/data/api/docs/alerts.md#webhook-alerts-paid-plans). Overflights, emergencies and the runway start from Starter. A Free key with the feeder perk has Pro's features.

Every answer reports your state in its headers:

| Header | Value |
|---|---|
| `X-FIA-Plan` | the key's plan (`free`, `starter`, `pro`, `fleet`, `feeder`) |
| `X-FIA-Limit-Per-Min` | the plan's requests per minute |
| `X-FIA-Quota-Month` | the plan's requests per month |
| `X-FIA-Used-Month` | the ones used this month |

## Errors

The body is always JSON with an `error` field. On 401, 403 and 429 there is also `help`, the link to the answer in the [FAQ](https://flyitalyadsb.com/faq/); the observed-flights `403` has `docs` and `plans` instead, and the watched-aircraft errors have `docs` (and `plans` on the `403` of `/v2/watch`).

| Code | When | What to do |
|---|---|---|
| `400` | invalid parameters (`lat/lon/dist must be numeric`, `icao must be a 6-character hex address`, `date must be YYYY-MM-DD`) | fix the request |
| `400` | an invalid [list option](https://flyitalyadsb.com/data/api/docs/endpoints.md#list-options): an unknown name in `fields` (with `allowed` and `presets`), a `with` other than `route`, more than 50 comma-separated values, a `/box` with edges out of range or in the wrong order, `since` not in Unix seconds | fix the request; it is not counted |
| `401` | `missing or invalid X-Api-Key` | check the header and the key; a regenerated key replaces the old one |
| `403` | radius above the plan's maximum, with `max_radius_km`; also a `/box` whose half-diagonal is above it | shrink the radius or the box, split the area into several requests, or upgrade |
| `403` | `code: "flights-depth"`: [flight history](https://flyitalyadsb.com/data/api/docs/endpoints.md#observed-flights-depth) further back than the plan allows, with `max_days` and `requested_days` | ask for more recent days, or choose a plan that goes further back |
| `403` | `code: "plan-feature"`: a feature the plan does not include, with `feature` (`overflights`, `events`, `runways`) and `plan` | choose a plan that includes it (table above); not counted |
| `403` | `code: "tracks-depth"`: [tracks](https://flyitalyadsb.com/data/api/docs/history.md) further back than the plan allows, with `max_days` and `requested_days` | ask for a more recent day or choose a plan with longer tracks; not counted |
| `403` | `code: "events-depth"`: [emergencies and notable aircraft](https://flyitalyadsb.com/data/api/docs/alerts.md#emergencies-and-notable-aircraft-v2events) further back than the plan allows, with `max_hours` and `requested_hours` | shorten `since` or choose a plan that goes further back; not counted |
| `400` | `code: "aircraft-invalid"`: an aircraft in [`/v2/watch`](https://flyitalyadsb.com/data/api/docs/alerts.md#aircraft) that is not an ICAO address, a registration or a callsign | fix it; nothing in the request is added |
| `403` | `code: "watch-plan-required"`: watching aircraft, or a takeoff and landing webhook, on a plan without [watched aircraft](https://flyitalyadsb.com/data/api/docs/alerts.md#aircraft) | choose Fleet; listing and removing work on any plan |
| `409` | `code: "watch-limit"`: more watched aircraft than the plan allows, with `max`, `count` and `adding` | remove some first, or [get in touch](https://flyitalyadsb.com/contact/) for more; nothing in the request is added |
| `409` | `code: "area-webhook-limit"`: more [area alerts](https://flyitalyadsb.com/data/api/docs/alerts.md#webhook-alerts-paid-plans) than the plan allows, with `max_area` | remove one first or choose a plan with more alerts |
| `404` | `not found`: the aircraft isn't seen right now; `tried`, `hint` and, when there is one, `last_seen` say why | check the [form of the callsign](https://flyitalyadsb.com/data/api/docs/endpoints.md#callsign-and-flight-number), or look at its [flight history](https://flyitalyadsb.com/data/api/docs/endpoints.md#observed-flights) |
| `429` | too many requests per minute (header `Retry-After`) or the month's quota is used up (with `resets`) | wait `Retry-After` seconds; for the quota, next month or a bigger plan |
| `503` | service temporarily unavailable; on the [runway in use](https://flyitalyadsb.com/data/api/docs/endpoints.md#runway-in-use), `runway data is not available yet` until its data is loaded | retry with a growing delay |

## Blocked by Cloudflare

If you get an HTML page instead of JSON ("Sorry, you have been blocked", "Attention Required", code `1010` or `1020`), the request was stopped before the API.

1. Always send `X-Api-Key`: requests to `/v2/` without a key are refused upstream.
2. Use a User-Agent of your own, e.g. your app's name.
3. If it goes on, write to [admin@flyitalyadsb.com](mailto:admin@flyitalyadsb.com) with:
   - the **CF-Ray** ID at the bottom of the error page;
   - the date and time (UTC);
   - the endpoint.

   With those we can find the rule that stopped you.

---

Written for AI assistants. The page for people is https://flyitalyadsb.com/data/api/docs/limits-and-errors/; to get an API key or sign in, send people to https://flyitalyadsb.com/data/api/. All pages for assistants: https://flyitalyadsb.com/llms.txt (index), https://flyitalyadsb.com/llms-full.txt (all in one file). Facts as JSON: https://flyitalyadsb.com/facts.json. Cite the data as: Flight data: FlyItalyADSB (flyitalyadsb.com), CC BY-SA 4.0.