Error handling
Caching and monitoring: Caching & monitoring.
Platform errors (401, 403, 422, 429, 5xx, retry/backoff, rate-limit headers): Error Handling.
Aircraft lookup: found is not a 404
The registration endpoint always returns 200 when the request itself is valid — even when the tail number is not in the SkyLink aircraft registry. Do not treat a missing aircraft as an HTTP error.
| Situation | HTTP status | How to detect |
|---|---|---|
| Registration known | 200 | found: true |
| Registration unknown | 200 | found: false |
| Malformed path segment | 404 | HTTP status code |
Always check found before reading aircraft.* fields. Reading aircraft.icao_type on a found: false response will raise a KeyError.
Live ADS-B: empty aircraft[] is not an error
GET /adsb/aircraft returns 200 with aircraft: [] when no aircraft match the requested filter (radius, bbox, or callsign). This is a valid empty result — do not show an error banner. The feed is live; aircraft move in and out of your filter area in seconds.
Additionally, never cache live ADS-B responses. The feed refreshes every few seconds; a cached position is stale by the time the next render fires.
import os
import requests
HEADERS = {
"X-RapidAPI-Key": os.getenv("RAPIDAPI_KEY", "YOUR_RAPIDAPI_KEY"),
"X-RapidAPI-Host": "skylink-api.p.rapidapi.com",
}
BASE = "https://skylink-api.p.rapidapi.com"
def lookup_registration(registration: str) -> dict | None:
"""
Returns aircraft dict or None when not found.
Always checks the `found` field — never treats found=false as an error.
"""
r = requests.get(
f"{BASE}/aircraft/registration/{registration}",
headers=HEADERS,
timeout=(10, 15),
)
r.raise_for_status()
data = r.json()
if not data.get("found"):
print(f"Registration {registration} not in registry (found=false).")
return None
return data["aircraft"]
def main() -> None:
ac = lookup_registration("N636JB")
if ac:
print(f"Found: {ac['registration']} / {ac['icao_type']} / {ac['owner_operator']}")
else:
print("Show empty state to user — aircraft not in registry.")
if __name__ == "__main__":
main()For 429 and 5xx responses, use the retry helper on Error Handling.
Related: Aircraft Lookup · ADS-B · Production patterns