Limits and errors

The Free plan also has a cap of 100 requests per minute per IP.

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 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 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 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 go, overflights, emergencies and notable aircraft, the runway in use and how many area alerts. 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; 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: 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 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 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 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 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	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 for more; nothing in the request is added
409	code: "area-webhook-limit": more area alerts 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, or look at its flight history
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, 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 [email protected] 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.