Error Handling

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

{
  "code": "UNAUTHORIZED",
  "message": "Access denied due to invalid subscription key. Make sure to provide a valid key for an active subscription.",
  "timestamp": "2026-01-15T18:56:00.0000000Z",
  "traceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "path": "/api/v1/metars/KJFK"
}

{
  "code": "TIER_RESTRICTED",
  "message": "This endpoint is not available on the Student Pilot tier. Please upgrade to Private Pilot or higher.",
  "timestamp": "2026-01-15T18:56:00.0000000Z",
  "traceId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "path": "/api/v1/notams/KJFK"
}

{
  "code": "RATE_LIMIT_EXCEEDED",
  "message": "Too many requests. Please slow down and try again shortly.",
  "retryAfterSeconds": 45,
  "timestamp": "2026-01-15T18:56:00.0000000Z",
  "traceId": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "path": "/api/v1/metars/KJFK"
}

{
  "code": "QUOTA_EXCEEDED",
  "message": "You have reached your monthly API call limit.",
  "quotaResetsAt": "2026-03-15T06:00:00.0000000Z",
  "timestamp": "2026-01-15T18:56:00.0000000Z",
  "traceId": "d4e5f6a7-b8c9-0123-defa-234567890123",
  "path": "/api/v1/metars/KJFK"
}

{
  "code": "BACKEND_UNAVAILABLE",
  "message": "The API backend is temporarily unavailable. Please try again shortly.",
  "timestamp": "2026-01-15T18:56:00.0000000Z",
  "traceId": "e5f6a7b8-c9d0-1234-efab-345678901234",
  "path": "/api/v1/metars/KJFK"
}

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

// 503 — external service unavailable (includes service field)
{
  "code": "EXTERNAL_SERVICE_UNAVAILABLE",
  "message": "The MagneticVariation service is temporarily unavailable.",
  "service": "MagneticVariationService",
  "timestamp": "2026-01-15T19:02:00.0000000Z",
  "traceId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "path": "/api/v1/navlog"
}

{
  "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:00.0000000Z",
  "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()
    // Every error has: { code, message, timestamp, traceId, path }

    switch (body.code) {
      case 'UNAUTHORIZED':
        throw new Error('Invalid API key')

      case 'TIER_RESTRICTED':
        throw new Error(body.message) // "...upgrade to Private Pilot..."

      case 'METAR_NOT_FOUND':
        return null // No METAR for this station — expected

      case 'RATE_LIMIT_EXCEEDED':
        // Retry after the indicated delay
        throw new Error(`Rate limited. Retry in ${body.retryAfterSeconds}s`)

      case 'QUOTA_EXCEEDED':
        // Monthly quota exhausted — not retryable
        throw new Error(`Quota exceeded. Resets at ${body.quotaResetsAt}`)

      case 'BACKEND_UNAVAILABLE':
        // Safe to retry with backoff
        throw new Error(body.message)

      case 'EXTERNAL_SERVICE_UNAVAILABLE':
        // body.service identifies which service is down
        throw new Error(`${body.message} (service: ${body.service})`)

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

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