Fehlerbehandlung

Wenn eine Anfrage fehlschlägt, ist der Antwort-Body JSON — sein Aufbau hängt jedoch davon ab, welche Schicht den Aufruf abgelehnt hat. Ihr Client sollte zuerst nach dem HTTP-Status verzweigen und den Body anschließend nach den folgenden Regeln auswerten. Diese Seite ist die maßgebliche Referenz für die plattformweite Fehlerbehandlung über alle API-Versionen (/v2, /v3, /v3.1) und alle Endpoints hinweg.

Authentifizierungsfehler unterscheiden sich zwischen den beiden Kanälen —

Lesen Sie immer Content-Type: application/json. Gehen Sie nicht davon aus, dass jeder Statuscode dasselbe Fehlerformat hat.

Die Referenzseiten der Endpoints dokumentieren nur Fehler, deren Bedeutung oder detail-Text für die jeweilige Ressource spezifisch ist (zum Beispiel fehlende METAR-Station vs. nicht herausgegebene TAF). Für Authentifizierung, Validierung, Rate Limits und Serverfehler verweisen sie auf diese Seite.

Authentifizierungs- und Kontingentfehler

Diese Fehler treten auf, bevor die Datenschicht erreicht wird oder anstatt sie zu erreichen. Der Body verwendet message oder code, nicht detail.

401 — fehlender oder ungültiger API-Schlüssel

{
  "code": "missing_api_key",
  "message": "Provide your key in the x-api-key header."
}

Der Schlüssel wird ausschließlich aus dem Header x-api-key gelesen — die Übergabe als Query-Parameter wird nicht akzeptiert und liefert ebenfalls 401.

403 — Endpoint nicht in Ihrem Tarif enthalten

{
  "code": "plan_forbidden",
  "message": "This endpoint is not included in your plan."
}

429 — Missbrauchsgrenze erreicht

{
  "message": "Too many requests"
}

Siehe Rate Limits — bei der direkten API ist dies die tägliche Obergrenze zum Schutz vor Missbrauch, nicht Ihr monatliches Kontingent.

{
  "type": "object",
  "required": ["message"],
  "properties": {
    "message": { "type": "string" }
  },
  "additionalProperties": true
}

Korrigieren Sie den Schlüssel oder das Abonnement — wiederholen Sie 401 oder 403 nicht. Bei 429 warten Sie ab und wiederholen die Anfrage; siehe Regeln für Wiederholungsversuche und Rate Limits zu den Kontingent-Headern.

Die Einrichtung der Header ist unter Erste Schritte beschrieben.

Validierungsfehler (422)

Erreicht die Anfrage SkyLink, besteht aber die Eingabevalidierung nicht, ist detail ein Array von Objekten:

{
  "detail": [
    {
      "type": "string_too_short",
      "loc": ["path", "icao"],
      "msg": "String should have at least 4 characters",
      "input": "KF",
      "ctx": { "min_length": 4 }
    }
  ]
}

{
  "type": "object",
  "required": ["detail"],
  "properties": {
    "detail": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["type", "loc", "msg", "input"],
        "properties": {
          "type": { "type": "string" },
          "loc": { "type": "array", "items": { "type": "string" } },
          "msg": { "type": "string" },
          "input": { "type": "string" },
          "ctx": { "type": "object" }
        },
        "additionalProperties": true
      }
    }
  },
  "additionalProperties": false
}

Nicht wiederholen — korrigieren Sie die Anfrageparameter und senden Sie die Anfrage erneut.

Server- und Upstream-Fehler (5xx)

Wenn SkyLink oder ein vorgelagerter Datendienst ausfällt:

{
  "detail": "Internal Server Error"
}

{
  "type": "object",
  "required": ["detail"],
  "properties": {
    "detail": { "type": "string" }
  },
  "additionalProperties": false
}

Wiederholen Sie die Anfrage mit exponentiellem Backoff (max. 3 Versuche). Siehe Regeln für Wiederholungsversuche.

Nicht gefunden (404)

404-Antworten verwenden die String-Form von detail bei SkyLink, aber Meldung und Bedeutung sind endpointspezifisch — ein METAR ohne Station, eine TAF ohne Vorhersage, ein unbekannter Flughafen-ICAO-Code und ein fehlender historischer Flug haben jeweils eine andere Semantik. Dokumentieren Sie 404 auf jeder Referenzseite (oder im Integrationsleitfaden des Abschnitts, wenn sich das Muster über mehrere Endpoints erstreckt). Duplizieren Sie hier nicht jede Variante; verlinken Sie aus Ihrem Handler auf die Seite, die zum aufgerufenen Endpoint passt.

Wichtig: Einige Endpoints liefern statt 404 ein leeres Ergebnis mit HTTP 200 (zum Beispiel die Luftfahrzeugsuche, wenn kein Kennzeichen passt). Prüfen Sie die Referenzseite, bevor Sie alle „nicht gefunden“-Fälle auf 404 abbilden.

Tarifbedingte 401/403-Fehler beim historischen ADS-B (Abonnement zu niedrig für das Pfadpräfix) sind auf der Übersichtsseite zu historischem ADS-B dokumentiert, nicht hier.

Regeln für Wiederholungsversuche

import time
import requests

RETRYABLE = {429, 500, 502, 504}


def fetch_with_retry(url: str, headers: dict, params: dict | None = None, max_retries: int = 3) -> requests.Response:
    delay = 1.0
    for attempt in range(max_retries + 1):
        r = requests.get(url, headers=headers, params=params, timeout=(10, 15))
        if r.status_code not in RETRYABLE or attempt == max_retries:
            return r
        time.sleep(delay)
        delay *= 2
    return r

Zu Tarifkontingenten, Preisen für Mehrverbrauch und den Pfadstufen beim historischen ADS-B siehe Rate Limits.