Error handling

Caching and monitoring: Caching & monitoring.

Platform errors (401, 403, 422, 429, 5xx, retry/backoff, rate-limit headers): Error Handling.

Flight time: 422 — unrecognised airport codes

GET /ml/flight-time validates that both from and to resolve to known airports. An unknown or malformed code returns 422 with a detail message identifying which code failed.

Code	Meaning	Fix
`422`	`from` or `to` not recognised	Use a valid ICAO (4-letter, e.g. `KJFK`) or IATA (3-letter, e.g. `JFK`) code. Resolve via Airport Search.

Note: The result is a statistical average derived from historical operational data — not a real-time forecast. Wind and live en-route conditions are not model inputs. Disclose this when presenting estimates to passengers or schedulers.

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 fetch_flight_time(origin: str, destination: str, aircraft: str | None = None) -> dict | None:
    """
    Fetch ML flight time estimate.
    Raises ValueError on 422 (invalid airport code).
    """
    params: dict[str, str] = {"from": origin, "to": destination}
    if aircraft:
        params["aircraft"] = aircraft
    r = requests.get(
        f"{BASE}/ml/flight-time",
        headers=HEADERS,
        params=params,
        timeout=(10, 15),
    )
    if r.status_code == 422:
        detail = r.json().get("detail", "invalid airport code")
        raise ValueError(f"422 Unprocessable: {detail}")
    r.raise_for_status()
    return r.json()


# Valid request — KJFK to KLAX
if __name__ == "__main__":
    data = fetch_flight_time("KJFK", "KLAX", aircraft="B738")
    if data:
        print(
            f"Estimated: {data['estimated_hours_display']}  "
            f"({data['min_minutes']}–{data['max_minutes']} min range)"
        )
        print("Statistical average — actual time varies with winds and routing.")
    else:
        print("No estimate returned.")

    try:
        fetch_flight_time("ZZZZ", "KLAX")
    except ValueError as exc:
        print(f"Caught expected error: {exc}")

Carbon emissions (GET /carbon/estimate) are documented in v3.1 Carbon — that endpoint is not available in the v3 API.

For transient failures (429, 5xx), use the retry helper on Error Handling.

Flight time: 422 — unrecognised airport codes

On this page