Operations

Errors and error codes

Every error comes with a fixed code, an explanation in German and, where relevant, the affected parameter.

Error response format

Every error comes as JSON with a fehler object and the matching HTTP status:

Response (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"
  }
}

Field	Meaning
`code`	Fixed, machine-readable code. Your code reacts to this.
`nachricht`	Explanation for humans, in German. The wording may change; do not rely on it.
`parameter`	Affected parameter, if there is one
`doku`	Link to this page. The API always points to the German docs, even for this page.

All error codes

Status	Code	Cause	Fix
400	`parameter_fehlt`	A required parameter is missing.	Add the parameter. The message names it.
400	`ungueltiger_parameter`	Wrong format, value outside the allowed range, or not in the list of allowed values. Also: CSV requested for a single value.	Check the format and range in the dataset's reference.
400	`unbekannter_parameter`	This dataset does not have that parameter, usually a typo.	The message lists the allowed names.
401	`schluessel_fehlt`	No Authorization header, or no Bearer key in it.	Set the header, check the environment variable.
401	`schluessel_ungueltig`	Key unknown, incomplete or revoked.	Check in your account, generate a new key if needed.
404	`kein_wert`	There is no official value for this effective date: before the history begins, or not promulgated yet.	Show your users a notice, do not guess. See Effective dates.
404	`unbekannter_datensatz`	The dataset in the path does not exist.	Check the spelling; list at /datensaetze.
404	`unbekannter_endpunkt`	The path does not match any endpoint, for example /verlauf on a calculator.	Check the endpoints in the REST API docs.
429	`kontingent_erreicht`	This month's quota is used up.	Wait until the first of the month, or change your plan.
500	`interner_fehler`	Error on our side.	Retry with a delay. If it persists, contact us.

Handling errors in code

400: The request is wrong. Retrying will not help; fix it.
401: Check the key. Retrying will not help.
404 with kein_wert: not a bug in your software. Show your users that the value is not set yet, instead of using an old or estimated value.
429: The quota only frees up again on the first of the month. Changing your plan raises it immediately.
500 and network errors: retry with a growing delay, for example after 0.3 and 0.6 seconds.

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;                       // show a notice, don't guess
if (res.status === 429) throw new Error("Quota used up");           // only available again next month
if (res.status >= 500) throw new Error("Try again later");          // retry with a delay
throw new Error(`${fehler.code}: ${fehler.nachricht}`);           // 400 and 401: fix the request or the key

Errors in the SDK, CLI and MCP

Access method	How the error arrives
SDK JavaScript	QuellenkontorFehler with status, code and parameter. Without a connection: status 0, code netzwerk. If the server responds without a readable error: code unbekannt
SDK Python	QuellenkontorFehler with status, code and parameter. Without a connection: status 0, code netzwerk
CLI	A line on stderr: Fehler, status, code and message. Exit code 1
MCP server	Tool result with isError and the same codes; HTTP 401 if the key is missing

If a value looks wrong

If a value does not match an official source you know of, report it through the contact form. Name the request, the value, and the source that shows something different. We check it against the primary source and record every correction in the changelog. With webhooks, your software learns about it as a korrektur event.

Something missing or unclear? Write to us and we will extend the docs.