Error Handling

{
  "statusCode": 429,
  "message": "Rate limit is exceeded. Try again in 52 seconds."
}

{
  "error": "This endpoint is not available on the Free tier. Please upgrade to Starter or Professional."
}

{
  "code": "METAR_NOT_FOUND",
  "message": "No current METAR available for station 'KXYZ'",
  "timestamp": "2026-01-15T18:56:00Z",
  "traceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "path": "/api/v1/metars/KXYZ"
}

{
  "code": "VALIDATION_ERROR",
  "message": "One or more validation errors occurred.",
  "validationErrors": {
    "latitude": [
      "Latitude must be between -90 and 90 degrees"
    ],
    "radiusNm": [
      "Radius must be between 0 and 100 nautical miles"
    ]
  },
  "timestamp": "2026-01-15T18:56:00Z",
  "traceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "path": "/api/v1/notams/radius"
}

async function fetchMetar(icaoCode: string): Promise<Metar | null> {
  const response = await fetch(
    `https://api.preflightapi.com/api/v1/metars/${icaoCode}`,
    {
      headers: {
        'Ocp-Apim-Subscription-Key': process.env.PREFLIGHT_API_KEY!,
      },
    },
  )

  if (!response.ok) {
    const body = await response.json()

    // Gateway errors have { statusCode, message }
    // Tier-gating errors have { error }
    // Backend errors have { code, message, traceId, ... }

    switch (response.status) {
      case 401:
        // Gateway: invalid key
        throw new Error(body.message)

      case 403:
        // Could be tier-gating ({ error }) or quota exceeded ({ statusCode, message })
        throw new Error(body.error || body.message)

      case 404:
        // Backend: resource not found
        if (body.code === 'METAR_NOT_FOUND') {
          return null // No METAR available for this station
        }
        throw new Error(body.message)

      case 429:
        // Gateway: rate limited — check Retry-After header
        throw new Error(body.message)

      case 503:
        // Backend: external service down — safe to retry
        throw new Error(body.message)

      default:
        // Backend error — log traceId for support
        console.error(`API error [${body.code}]: ${body.message}`)
        if (body.traceId) console.error(`Trace ID: ${body.traceId}`)
        throw new Error(body.message)
    }
  }

  return response.json() as Promise<Metar>
}