Skip to Content
API für EntwicklerFehler

Fehler

Jede Fehlerantwort ist JSON mit einem Maschinen-Code error und einem Klartext message:

{ "error": "kosit_validation", "message": "Die Rechnung hat die KoSIT-Validierung nicht bestanden …" }

Interne Details oder Stacktraces werden nie ausgegeben.

Katalog

400 — validation

Der Request ist ungültig: fehlende Pflichtfelder, ein Wert außerhalb der Grenzen, unbekannte Zusatzfelder, fehlender idempotencyKey oder ungültiges JSON. Bei Feldfehlern nennt issues[] die betroffenen Pfade. → Request korrigieren und neu senden.

401 — unauthorized

Der Schlüssel ist ungültig, widerrufen oder abgelaufen. → Schlüssel prüfen bzw. im Konto einen neuen API-Schlüssel erstellen.

403 — forbidden

Zwei Ursachen (die message unterscheidet sie):

  • Tarif zu niedrig – die API erfordert mindestens Basic. Ein Free-Konto wird abgelehnt.
  • Vom Betreiber gesperrt – der Schlüssel wurde administrativ stillgelegt (nicht vom Nutzer widerrufen). → Support kontaktieren.

422 — kosit_validation / invalid_state

Die Daten sind formal ok, aber die Rechnung ist nicht normkonform und wurde nicht festgeschrieben:

  • kosit_validation – die E-Rechnung besteht die offizielle KoSIT-Prüfung nicht. Häufige Ursache: reverseCharge oder intraCommunity ohne Käufer-USt-IdNr. (recipient.vatId). Das Feld validation enthält die Prüfmeldungen.
  • invalid_state – eine Vorbedingung fehlt, z. B. das Unternehmensprofil des Kontos ist nicht ausgefüllt. → Im flstr-Konto nachtragen.

→ Rechnungsdaten korrigieren (ein bloßes Wiederholen hilft nicht).

429 — rate_limit vs. daily_cap

Zwei verschiedene Fälle – Ihre App muss sie unterscheiden:

  • error: "rate_limit" — das kurzfristige Anfrage-Limit (Anfragen pro Minute) ist erreicht. → Kurz warten und den Request wiederholen (z. B. mit exponentiellem Backoff).
  • error: "daily_cap" — das Tages-Limit für neue Rechnungen ist erschöpft. → Nicht wiederholen; bis zum nächsten Tag warten oder beim Betreiber eine Anhebung des Limits anfragen.

Ein Wiederholungs-Automatismus, der beide gleich behandelt, läuft bei daily_cap ins Leere.

503 — rate_limiter_unavailable

Der Rate-Limiter ist vorübergehend nicht erreichbar; der Request wurde sicherheitshalber abgelehnt (kein Beleg entstand). → Nach kurzer Zeit erneut versuchen.

404 — not_found (nur GET)

Der abgerufene Beleg gehört nicht zum Konto des Schlüssels oder existiert nicht.

Wiederholen — ja oder nein?

CodeWiederholen?
400, 422Nein – erst die Daten korrigieren.
401, 403Nein – erst Schlüssel/Tarif klären.
429 rate_limitJa – kurz warten, dann erneut (mit demselben idempotencyKey).
429 daily_capNein – bis morgen / Limit anfragen.
503Ja – kurz warten, dann erneut (mit demselben idempotencyKey).

Beim Wiederholen immer denselben idempotencyKey verwenden – dann kann kein Duplikat entstehen, selbst wenn ein vorheriger Versuch die Rechnung doch schon erzeugt hatte. Siehe Idempotenz.

Kunden-UpsertÜberblick