Error Handling

SkyLink API uses standard HTTP status codes and returns structured JSON error responses.

Error Response Format

All errors follow a consistent structure:

{
  "error": "Short error title",
  "message": "Human-readable description of what went wrong",
  "code": "MACHINE_READABLE_ERROR_CODE"
}

HTTP Status Codes

Status Code	Meaning	When It Occurs
200	Success	Request completed successfully
400	Bad Request	Invalid parameters, missing required fields, or malformed input
401	Unauthorized	Missing or invalid API key
404	Not Found	Resource not found (airport, flight, etc.)
422	Validation Error	Request parameters fail validation (wrong type, out of range)
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Unexpected server error
502	Bad Gateway	Upstream data source unavailable
504	Gateway Timeout	Upstream data source timed out

Common Error Codes

Authentication Errors

Code	Description
MISSING_API_KEY	No X-RapidAPI-Key header provided
INVALID_API_KEY	API key is not valid
INVALID_RAPIDAPI_SECRET	RapidAPI proxy secret is not valid

Resource Errors

Code	Description
AIRPORT_NOT_FOUND	No airport found for the given ICAO/IATA code
AIRLINE_NOT_FOUND	No airline found for the given ICAO/IATA code
FLIGHT_NOT_FOUND	No flight status available for the given flight number
AIRCRAFT_NOT_FOUND	No aircraft found for the given registration or ICAO24
NO_CHARTS_AVAILABLE	No charts found for the given airport

Validation Errors

Code	Description
INVALID_ICAO	ICAO code is not valid (must be 3-4 alphanumeric characters)
INVALID_IATA	IATA code is not valid (must be 3 alphabetic characters)
INVALID_COORDINATES	Latitude or longitude values are out of range
MISSING_PARAMETER	A required query parameter is missing

Data Source Errors

Code	Description
UPSTREAM_ERROR	External data source returned an error
UPSTREAM_TIMEOUT	External data source did not respond in time
SERVICE_UNAVAILABLE	Feature is temporarily unavailable

Handling Errors

Python Example

import httpx

response = httpx.get(
    "YOUR_API_BASE_URL/v3/weather/metar/XXXX",
    headers={"X-RapidAPI-Key": "YOUR_API_KEY"},
)

if response.status_code == 200:
    data = response.json()
elif response.status_code == 401:
    print("Check your API key")
elif response.status_code == 404:
    error = response.json()
    print(f"Not found: {error['message']}")
else:
    print(f"Error {response.status_code}: {response.text}")

JavaScript Example

try {
  const response = await fetch(
    "YOUR_API_BASE_URL/v3/weather/metar/XXXX",
    { headers: { "X-RapidAPI-Key": "YOUR_API_KEY" } }
  );

  if (!response.ok) {
    const error = await response.json();
    console.error(`${error.code}: ${error.message}`);
    return;
  }

  const data = await response.json();
} catch (err) {
  console.error("Network error:", err);
}

Retry Strategy

For 429, 500, 502, and 504 errors, implement exponential backoff:

1. Wait 1 second, retry
2. Wait 2 seconds, retry
3. Wait 4 seconds, retry
4. Give up after 3 retries

For 400, 401, 404, and 422 errors, do not retry — fix the request instead.