Betrieb

Fehler und Fehlercodes

Jeder Fehler kommt mit einem festen Code, einer Erklärung auf Deutsch und, wo es passt, dem betroffenen Parameter.

Aufbau einer Fehlerantwort

Jeder Fehler kommt als JSON mit einem Objekt fehler und dem passenden HTTP-Status:

Antwort (400)

{
  "fehler": {
    "code": "ungueltiger_parameter",
    "nachricht": "Der Parameter datum muss ein Datum im Format JJJJ-MM-TT sein, zum Beispiel 2027-01-15.",
    "parameter": "datum",
    "doku": "https://quellenkontor.dev/docs/fehler"
  }
}

Feld	Bedeutung
`code`	Fester, maschinenlesbarer Code. Darauf reagiert dein Code.
`nachricht`	Erklärung auf Deutsch für Menschen. Der Wortlaut kann sich ändern, verlass dich nicht darauf.
`parameter`	Betroffener Parameter, falls es einen gibt
`doku`	Link auf diese Seite

Alle Fehlercodes

Status	Code	Ursache	Lösung
400	`parameter_fehlt`	Ein Pflichtparameter fehlt.	Parameter ergänzen. Die Meldung nennt ihn.
400	`ungueltiger_parameter`	Falsches Format, Wert außerhalb des erlaubten Bereichs oder nicht in der Liste der erlaubten Werte. Auch: CSV für einen Einzelwert angefragt.	Format und Bereich in der Referenz des Datensatzes nachsehen.
400	`unbekannter_parameter`	Den Parameter gibt es für diesen Datensatz nicht, meist ein Tippfehler.	Die Meldung zählt die erlaubten Namen auf.
401	`schluessel_fehlt`	Kein Header Authorization oder kein Bearer-Schlüssel darin.	Header setzen, Umgebungsvariable prüfen.
401	`schluessel_ungueltig`	Schlüssel unbekannt, unvollständig oder gesperrt.	Im Konto prüfen, bei Bedarf neuen Schlüssel erzeugen.
404	`kein_wert`	Für diesen Stichtag gibt es keinen amtlichen Wert: vor Beginn des Verlaufs oder noch nicht verkündet.	Deinen Nutzern einen Hinweis zeigen, nicht raten. Siehe Stichtage.
404	`unbekannter_datensatz`	Den Datensatz im Pfad gibt es nicht.	Schreibweise prüfen, Liste unter /datensaetze.
404	`unbekannter_endpunkt`	Der Pfad passt zu keinem Endpunkt, etwa /verlauf bei einem Rechner.	Endpunkte in der REST-Doku nachsehen.
429	`kontingent_erreicht`	Das Kontingent des Monats ist aufgebraucht.	Bis zum Monatsersten warten oder Tarif wechseln.
500	`interner_fehler`	Fehler auf unserer Seite.	Mit Pause erneut versuchen. Tritt er dauerhaft auf, schreib uns.

Fehler im Code behandeln

400: Die Anfrage ist falsch. Wiederholen hilft nicht, korrigiere sie.
401: Schlüssel prüfen. Wiederholen hilft nicht.
404 mit kein_wert: Kein Fehler deiner Software. Zeig deinen Nutzern, dass der Wert noch nicht feststeht, statt einen alten oder geschätzten Wert zu nehmen.
429: Das Kontingent ist erst am Monatsersten wieder frei. Ein Tarifwechsel hebt es sofort an.
500 und Netzfehler: Mit wachsender Pause erneut versuchen, zum Beispiel nach 0,3 und 0,6 Sekunden.

JavaScript

const res = await fetch(url, { headers: { Authorization: `Bearer ${schluessel}` } });
if (res.ok) return await res.json();

const { fehler } = await res.json();
if (fehler.code === "kein_wert") return null;                       // Hinweis zeigen, nicht raten
if (res.status === 429) throw new Error("Kontingent aufgebraucht"); // erst im nächsten Monat wieder
if (res.status >= 500) throw new Error("Später erneut versuchen");  // mit Pause wiederholen
throw new Error(`${fehler.code}: ${fehler.nachricht}`);           // 400 und 401: Anfrage oder Schlüssel korrigieren

Fehler in SDK, CLI und MCP

Zugang	So kommt der Fehler an
SDK JavaScript	QuellenkontorFehler mit status, code und parameter. Ohne Verbindung: status 0, code netzwerk. Antwortet der Server ohne lesbaren Fehler: code unbekannt
SDK Python	QuellenkontorFehler mit status, code und parameter. Ohne Verbindung: status 0, code netzwerk
CLI	Zeile auf stderr: Fehler, Status, Code und Meldung. Rückgabewert 1
MCP-Server	Werkzeugergebnis mit isError und denselben Codes, bei fehlendem Schlüssel HTTP 401

Wenn ein Wert falsch aussieht

Wenn ein Wert nicht zu der amtlichen Quelle passt, die du kennst, melde es über das Kontaktformular. Nenne Abfrage, Wert und die Quelle, die etwas anderes zeigt. Wir prüfen gegen die Primärquelle und tragen jede Korrektur ins Änderungsprotokoll ein. Mit Webhooks erfährt deine Software davon als Ereignis korrektur.

Fehlt etwas oder ist etwas unklar? Schreib uns, wir ergänzen die Doku.