Fehlercodes-Referenz

Diese Seite ist die zentrale Referenz für Fehlerantworten über alle fiskaly-APIs hinweg. Verwenden Sie den interaktiven Explorer unten, um Fehler zu suchen und zu filtern, oder scrollen Sie nach unten für die statischen Referenztabellen.

36 errors found

Statische Referenz

Beginnen Sie mit dem Fehlerbehebungs-Entscheidungsbaum, wenn Sie einen Fehler haben und eine schnelle Antwort benötigen, oder durchsuchen Sie die produktspezifischen Tabellen unten für detaillierte Fehlercodes.

Fehlerantwort-Format

Alle fiskaly-APIs geben Fehler in einem einheitlichen JSON-Format zurück:

{
  "status_code": 400,
  "error": "Bad Request",
  "code": "E_SOME_ERROR",
  "message": "Eine für Menschen lesbare Beschreibung des Fehlers"
}

Feld	Typ	Beschreibung
`status_code`	integer	HTTP-Statuscode
`error`	string	HTTP-Statustext
`code`	string	fiskaly-spezifischer Fehlercode (mit `E_`-Präfix)
`message`	string	Für Menschen lesbare Fehlerbeschreibung

HTTP-Statuscodes

2xx — Erfolg

Code	Bedeutung	Wann Sie ihn sehen
`200`	OK	Anfrage erfolgreich, Antwort-Body enthält das Ergebnis
`201`	Created	Ressource erfolgreich erstellt
`204`	No Content	Anfrage erfolgreich, kein Antwort-Body (z. B. DELETE-Vorgänge)

4xx — Client-Fehler

Diese weisen auf ein Problem mit Ihrer Anfrage hin. Wiederholen Sie nicht mit demselben Payload — beheben Sie zuerst das Problem.

Code	Bedeutung	Häufige Ursachen
`400`	Bad Request	Fehlerhaftes JSON, fehlende Pflichtfelder, ungültige Feldwerte
`401`	Unauthorized	Abgelaufener oder fehlender Access-Token, ungültige API-Zugangsdaten
`403`	Forbidden	Unzureichende Berechtigungen für die angeforderte Ressource
`404`	Not Found	Ressource existiert nicht oder falscher URL-Pfad
`409`	Conflict	Ressource existiert bereits (doppelter Erstellungsversuch)
`422`	Unprocessable Entity	Gültiges JSON, aber semantisch falsch (z. B. ungültiger Zustandsübergang)
`423`	Locked	Ressource ist derzeit durch einen anderen Vorgang gesperrt
`429`	Too Many Requests	Rate Limit überschritten — zurückhalten und mit exponentiellem Delay wiederholen

5xx — Server-Fehler

Diese weisen auf ein vorübergehendes Problem auf fiskaly-Seite hin. Sicher zum Wiederholen mit exponentiellem Backoff.

Code	Bedeutung	Aktion
`500`	Internal Server Error	Nach kurzer Verzögerung wiederholen; bei Persistenz status.fiskaly.com prüfen
`502`	Bad Gateway	Upstream-Dienst vorübergehend nicht verfügbar; wiederholen
`503`	Service Unavailable	Dienst vorübergehend für Wartung nicht verfügbar; wiederholen
`504`	Gateway Timeout	Anfrage upstream abgelaufen; mit längerem Timeout wiederholen

Authentifizierungsfehler

Dies sind die häufigsten Fehler, die Entwickler während der Integrierung begegnen.

Fehlercode	HTTP-Status	Ursache	Behebung
`E_UNAUTHORIZED_ACCESS`	401	Access-Token abgelaufen oder nicht angegeben	Mit API Key und Secret erneut authentifizieren
`E_INVALID_CREDENTIALS`	401	API Key oder Secret ist falsch	Zugangsdaten im HUB prüfen
`E_TOKEN_EXPIRED`	401	JWT Access-Token ist abgelaufen	Refresh-Token verwenden oder erneut authentifizieren
`E_ACCESS_FORBIDDEN`	403	Ihr API Key hat keine Berechtigung für diese Ressource	API Key-Berechtigungen im HUB prüfen

Token-Lebenszyklus

API Key + Secret  →  POST /auth  →  access_token (24h) + refresh_token (48h)
                                         │
                                         ├── Für alle API-Aufrufe verwenden
                                         │
                                         └── Bei 401 → erneut authentifizieren (nicht bei jeder Anfrage)

💡Authentifizieren Sie sich nicht bei jeder Anfrage neu

Der Access-Token ist 24 Stunden und der Refresh-Token 48 Stunden gültig. Eine erneute Authentifizierung bei jeder Anfrage verursacht unnötige Latenz im Kassierprozess. Cachen Sie den Token und erneuern ihn nur bei 401-Antworten.

SIGN DE — TSS-Fehler

Fehlercode	HTTP-Status	Ursache	Behebung
`E_TSS_NOT_FOUND`	404	TSS-ID existiert nicht	TSS-ID prüfen; alle TSS über `GET /tss` auflisten
`E_TSS_NOT_INITIALIZED`	400	TSS wurde noch nicht initialisiert	Alle notwendigen Schritte ausführen: TSS erstellen, auf `UNINITIALIZED` aktualisieren, Admin-PIN setzen, als Admin einloggen und TSS auf `INITIALIZED` setzen
`E_TSS_DISABLED`	400	TSS wurde deaktiviert	TSS kann keine Transaktionen mehr signieren, neues TSS erstellen
`E_TSS_IN_USE`	409	TSS wird durch eine andere Anfrage geändert	Warten und wiederholen
`E_CLIENT_NOT_FOUND`	404	Client-ID existiert nicht für dieses TSS	Client über `PUT /tss/{tss_id}/client/{client_id}` erstellen
`E_CLIENT_NOT_REGISTERED`	400	Client existiert, ist aber nicht registriert	Client vor dem Erstellen von Transaktionen registrieren
`E_TX_NOT_FOUND`	404	Transaktions-ID existiert nicht	Transaktions-ID und TSS-Kontext prüfen
`E_TX_INVALID_STATE`	422	Transaktion ist in einem Zustand, der diesen Vorgang nicht erlaubt	Aktuellen Transaktionszustand prüfen; Zustandsautomat befolgen
`E_EXPORT_NOT_FOUND`	404	Export-ID existiert nicht	Export-ID prüfen; Exporte benötigen möglicherweise Zeit zur Verarbeitung
`E_EXPORT_IN_PROGRESS`	409	Export wird noch generiert	Export-Status abfragen bis `state: COMPLETED`

SUBMIT DE-Fehler

Fehlercode	HTTP-Status	Ursache	Behebung
`E_ESTABLISHMENT_NOT_FOUND`	404	Betriebsstätten-ID nicht gefunden	Prüfen, ob die Betriebsstätte für Ihre Organisation existiert
`E_TAXPAYER_NOT_FOUND`	404	Steuerpflichtigen-Datensatz nicht gefunden	Zuerst Steuerpflichtigen-Ressource erstellen
`E_TAXPAYER_ADDRESS_NOT_FOUND`	404	Steuerpflichtigen-Adresse nicht konfiguriert	Adressdaten zur Steuerpflichtigen-Ressource hinzufügen
`E_TAXPAYER_PERSON_NOT_FOUND`	404	Steuerpflichtigen-Personen-Datensatz fehlt	Personendaten zur Steuerpflichtigen-Ressource hinzufügen
`E_SUBMISSION_NOT_FOUND`	404	Einreichungs-ID nicht gefunden	Einreichungs-ID prüfen; sicherstellen, dass die Einreichung erstellt wurde
`E_CLIENT_ADDITIONAL_DATA_NOT_FOUND`	404	Zusätzliche Client-Daten fehlen	Erforderliche zusätzliche Daten für den Client bereitstellen
`E_LOCKED_RESOURCE`	423	Ressource durch einen laufenden Vorgang gesperrt	Auf den Abschluss des aktuellen Vorgangs warten, dann wiederholen

DSFINVK DE-Fehler

Fehlercode	HTTP-Status	Ursache	Behebung
`E_CASH_REGISTER_NOT_FOUND`	404	Kassensystem nicht gefunden	Kassensystem zuerst über die DSFinV-K-API erstellen
`E_CASH_POINT_CLOSING_NOT_FOUND`	404	Kassenabschluss nicht gefunden	Abschluss-ID prüfen
`E_VAT_DEFINITION_NOT_FOUND`	404	Mehrwertsteuerdefinition nicht konfiguriert	MwSt-Definitionen vor dem Einfügen von Abschlüssen erstellen
`E_INVALID_CLOSING_DATA`	400	Abschluss-Payload entspricht nicht dem erwarteten Schema	Ihren Payload gegen die DSFinV-K-Spezifikation validieren

Unified API — Häufige Fehler

Diese Fehler werden über alle Unified API-Produkte hinweg geteilt (SIGN FR, SIGN IT, SIGN ES). Alle drei APIs verwenden dieselbe Authentifizierungs-, Organisations- und Ressourcenverwaltungsschicht.

Fehlercode	HTTP-Status	Ursache	Behebung
`E_ORGANIZATION_NOT_FOUND`	404	Organisations-ID existiert nicht	Org-ID prüfen; sicherstellen, dass sie unter der richtigen GROUP erstellt wurde
`E_TAXPAYER_NOT_COMMISSIONED`	400	Steuerpflichtiger existiert, Zustand ist nicht `COMMISSIONED`	Steuerpflichtigen-Zustand auf `COMMISSIONED` aktualisieren, bevor Vorgänge durchgeführt werden
`E_IDEMPOTENCY_KEY_REUSED`	409	Idempotenz-Key wurde bereits für eine andere Anfrage verwendet	Neue UUID für jede neue Anfrage generieren
`E_API_VERSION_NOT_SUPPORTED`	400	`X-Api-Version`-Header enthält nicht unterstütztes Datum	Aktuellste unterstützte Version verwenden (z. B. `2026-02-03`)
`E_SCOPE_IDENTIFIER_MISSING`	400	`X-Scope-Identifier`-Header nicht angegeben	Organisations-ID in `X-Scope-Identifier` einfügen
`E_SUBJECT_NOT_FOUND`	404	Subject (API Key) nicht gefunden	Prüfen, ob Subject unter der richtigen Organisation erstellt wurde
`E_TOKEN_INVALID`	401	Token ist fehlerhaft oder abgelaufen	Erneut über `POST /api/v1/auth/token` authentifizieren
`E_LOCATION_NOT_COMMISSIONED`	400	Standort existiert, ist aber nicht in Betrieb	Standort-Zustand auf `COMMISSIONED` aktualisieren
`E_SYSTEM_NOT_COMMISSIONED`	400	System existiert, ist aber nicht in Betrieb	System-Zustand auf `COMMISSIONED` aktualisieren

💡Idempotenz-Keys über alle Unified APIs

Alle Unified API-Produkte unterstützen den X-Idempotency-Key-Header bei ändernden Anfragen. Die Key-Value-Paare laufen nach 24 Stunden ab. Wenn Sie einen Key mit einem anderen Payload wiederverwenden, erhalten Sie 422 Unprocessable Entity. Wenn die ursprüngliche Anfrage noch verarbeitet wird, erhalten Sie 409 Conflict.

SIGN FR — Spezifische Fehler

Fehlercode	HTTP-Status	Ursache	Behebung
`E_RECORD_INVALID_OPERATION`	422	Datensatz-Vorgangstyp für aktuellen Zustand ungültig	Intention → Transaction-Ablauf prüfen; korrekte Reihenfolge sicherstellen
`E_RECORD_INTENTION_REQUIRED`	400	Transaktionsdatensatz ohne vorherige Intention erstellt	Zuerst einen Intentions-Datensatz erstellen, dann seine ID referenzieren
`E_TAXPAYER_CREDENTIALS_INVALID`	400	Französische Fiskalisierungs-Zugangsdaten (NF 525) ungültig	`tax_id_number` (SIREN) und Zugangsdaten prüfen
`E_CLOSURE_IN_PROGRESS`	409	Ein Fiskalabschluss läuft bereits	Auf den Abschluss des aktuellen Abschlusses warten

SIGN IT — Spezifische Fehler

Fehlercode	HTTP-Status	Ursache	Behebung
`E_RT_DEVICE_NOT_FOUND`	404	Registratore Telematico-Gerät nicht gefunden	Prüfen, ob das RT-Gerät erstellt und in Betrieb genommen wurde
`E_RT_SUBMISSION_FAILED`	502	Einreichung bei Agenzia delle Entrate fehlgeschlagen	Wiederholen; bei Persistenz AdE-Dienststatus prüfen
`E_LOTTERY_CODE_INVALID`	400	Belegslotterie-Code-Format ungültig	Sicherstellen, dass der Lotterie-Code 8 alphanumerische Zeichen hat
`E_FISCAL_CODE_INVALID`	400	Italienisches Codice fiscale-Format falsch	16-stelliges Fiskalcode-Format prüfen

SIGN ES — Validierungsfehler

SIGN ES gibt Validierungsfehler in einem validations-Array in der Antwort zurück, jedes mit einem code und einer description. Diese sind spezifisch für TicketBAI / Verifactu / SII-Einreichungen.

Validierungscode	Ursache
`V_TICKETBAI`	Unbekannter oder unbehandelter Fehler von TicketBAI
`V_XSD_SCHEMA_NOT_COMPLY`	XML-Datei entspricht nicht dem XML-Schema
`V_INVOICE_WITHOUT_LINES`	XML-Datei enthält keine Detailzeilen
`V_REQUIRED_FIELD_MISSING_OR_INCORRECT`	Pflichtdaten fehlen oder sind falsch
`V_INVOICE_ALREADY_REGISTERED`	Rechnung mit derselben Nummer/Serie/Jahr wurde bereits registriert
`V_SERVICE_NOT_AVAILABLE`	Empfangsdienst ist nicht verfügbar
`V_INCORRECT_SENDER_CERTIFICATE`	Absender-Zertifikat ist unbekannt
`V_INVALID_SENDER_CERTIFICATE`	Absender-Zertifikat ist nicht gültig
`V_WRONG_SIGNATURE`	Signaturvalidierung fehlgeschlagen
`V_INCORRECT_INVOICE_CHAINING`	Rechnungsverkettung war falsch
`V_INVALID_TBAI_LICENSE`	TicketBAI-Lizenz nicht registriert oder ungültig
`V_DEVICE_NOT_REGISTERED`	Gerätezertifikat zum Senden ist noch nicht registriert
`V_EXPIRED_SIGNATURE_CERTIFICATE`	Zum Signieren der TicketBAI-Datei verwendetes Zertifikat ist abgelaufen
`V_EXPIRED_SENDER_CERTIFICATE`	Absender-Zertifikat ist nicht gültig oder abgelaufen
`V_EXPIRED_SIGNER_CERTIFICATE`	Zum Signieren verwendetes Zertifikat ist nicht gültig oder abgelaufen
`V_FULL_AMOUNT_MISMATCH`	Summe der Zeilen-`full_amount`-Einträge stimmt nicht mit der Rechnungs-`full_amount` überein
`V_ISSUE_DATE_OUT_OF_RANGE`	Ausstellungsdatum ist älter als 20 Jahre oder liegt in der Zukunft
`V_INVALID_VAT_RATE`	Mehrwertsteuersatz ist kein gültiger Wert für die Region des Steuerpflichtigen
`V_INVOICE_ALREADY_CANCELLED`	Rechnung wurde bereits storniert
`V_INVOICE_ALREADY_CORRECTED`	Rechnung wurde bereits korrigiert
`V_INCOMPATIBLE_VAT_SYSTEMS`	Bereitgestellte Rechnungssysteme sind nicht miteinander kompatibel
`V_INCORRECT_ITEM_VAT_CALCULATION`	Ein Rechnungsposten hat eine falsch angewendete Mehrwertsteuerberechnung

📘SIGN ES Validierungsfehler sind nicht blockierend

Validierungsfehler erscheinen im validations-Array der Antwort, verhindern aber nicht unbedingt die Erstellung des Datensatzes. Prüfen Sie das state-Feld des Datensatzes (REJECTED oder FAILED), um festzustellen, ob der Fehler fatal war.

Timeout-Empfehlungen

Verschiedene Vorgänge haben unterschiedliche erwartete Dauern. Konfigurieren Sie Ihre Timeouts entsprechend:

Vorgang	Empfohlenes Timeout	Hinweise
Authentifizierung (`POST /auth`)	3–4 Sekunden	Schneller Vorgang; blockiert nicht den Kassiervorgang
Transaktionssignierung (`PUT /tx`)	3–5 Sekunden	Sollte den POS niemals blockieren
TSS-Erstellung / -Initialisierung	30 Sekunden	Einmalige Einrichtung; aufwändigere Verarbeitung
DSFinV-K-Kassenabschlüsse	Bis zu 10 Minuten	Aufwändige Verarbeitung mit großen Datensätzen
Export-Generierung	Polling-basiert	Asynchrones Polling verwenden, keine synchrone Wartezeit

⚠️Kassiervorgang niemals blockieren

Setzen Sie Transaktionssignierungs-Timeouts zwischen 3–5 Sekunden. Eine fehlende Signatur macht einen Beleg nicht nicht-konform (siehe AEAO zu 146a, Punkt 7). Fügen Sie einen Hinweis wie “TSS nicht verfügbar” zu unsignierten Belegen hinzu und nehmen Sie diese in den DSFinV-K-Export auf.

💡Timeouts konfigurierbar machen

Erlauben Sie Administratoren, Timeout-Werte (z. B. 1,5–5 Sekunden für Transaktionen) ohne Codeänderungen anzupassen. Dies spart Entwicklungszyklen und passt sich an unterschiedliche Netzwerkbedingungen an.

Wiederholungsstrategie

Verwenden Sie für vorübergehende Fehler (5xx, Timeouts, Rate Limits) exponentiellen Backoff:

async function callWithRetry(fn, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (attempt === maxRetries) throw error;

      const isRetryable =
        error.status >= 500 ||
        error.status === 429 ||
        error.code === "ETIMEDOUT";

      if (!isRetryable) throw error;

      const delay = Math.min(1000 * 2 ** attempt, 30000);
      await new Promise((r) => setTimeout(r, delay));
    }
  }
}

Fehlerbehebungs-Entscheidungsbaum

Einen Fehler erhalten?
  │
  ├── 401 Unauthorized
  │     └── Ist Ihr Token abgelaufen?
  │           ├── Ja → Mit API Key + Secret erneut authentifizieren
  │           └── Nein → Zugangsdaten im HUB prüfen
  │
  ├── 400 Bad Request
  │     └── Prüfen Sie das `message`-Feld, um zu sehen, welches Feld ungültig ist
  │           └── Ihren JSON-Payload gegen das API-Schema validieren
  │
  ├── 404 Not Found
  │     └── Existiert die Ressource?
  │           ├── ID prüfen (UUIDv4-Format)
  │           └── Sicherstellen, dass die Ressource in der richtigen Umgebung erstellt wurde (TEST vs. LIVE)
  │
  ├── 409 Conflict
  │     └── Ressource existiert bereits oder wird geändert
  │           └── GET verwenden, um aktuellen Zustand vor dem Wiederholen zu prüfen
  │
  ├── 429 Rate Limited
  │     └── Mit exponentiellem Delay zurückhalten
  │           └── Prüfen, ob Sie sich bei jeder Anfrage neu authentifizieren (nicht tun)
  │
  └── 5xx Server Error
        └── status.fiskaly.com prüfen
              ├── Bekannter Vorfall → Auf Lösung warten
              └── Kein Vorfall → Mit exponentiellem Backoff wiederholen; bei Persistenz Support kontaktieren

Service-Status

Überwachen Sie den fiskaly-Dienststatus unter status.fiskaly.com.

Häufige Integrierungsfehler

Dies sind die Fehler, die der fiskaly-Support am häufigsten von Teams während ihrer ersten Integrierung sieht. Sie zu vermeiden spart erhebliche Debugging-Zeit.

Fehler	Was passiert	Wie vermeiden
Erneute Authentifizierung bei jeder Anfrage	`429` Rate-Limit-Fehler; unnötige Latenz bei jedem Kassiervorgang	Access-Token cachen (24h TTL). Nur bei `401` erneut authentifizieren.
`admin_puk` nicht gespeichert	Admin-PIN kann nicht am TSS gesetzt werden; verbleibt im Zustand `UNINITIALIZED`	Den `admin_puk` aus der TSS-Erstellungsantwort sofort speichern.
UUIDs wiederverwenden	`409 Conflict`-Fehler beim Erstellen von TSS, Clients oder Transaktionen	Neue UUIDv4 für jeden Ressourcen-Erstellungsaufruf generieren.
Kassiervorgang bei Signierungsfehler blockieren	Kunden warten unendlich, wenn das TSS langsam oder nicht verfügbar ist	3–5 Sekunden Timeout für Signierungen setzen. Beleg mit “TSS nicht verfügbar” ausstellen und später wiederholen.
TEST-Zugangsdaten in LIVE verwenden (oder umgekehrt)	`401 Unauthorized` — Zugangsdaten sind umgebungsbezogen	Prüfen, ob Basis-URL zur Umgebung des API Keys passt. TEST und LIVE sind vollständig getrennt.
TSS-Initialisierung überspringen	`400 E_TSS_NOT_INITIALIZED` beim Erstellen von Clients oder Transaktionen	Alle notwendigen Schritte ausführen: TSS erstellen, auf `UNINITIALIZED` aktualisieren, Admin-PIN setzen, als Admin einloggen und TSS auf `INITIALIZED` setzen.
`tx_revision` nicht korrekt handhaben	`422 E_TX_INVALID_STATE` oder doppelte Transaktionsfehler	Mit `tx_revision=1` beginnen (ACTIVE), mit `tx_revision=2` abschließen (FINISHED). Immer inkrementieren.
Synchrones Export-Polling	Timeouts bei DSFinV-K-Export-Generierung (kann bis zu 10 Minuten dauern)	Asynchrones Polling verwenden: Export auslösen, dann Status-Endpunkt abfragen bis `state: COMPLETED`.
Timeouts fest kodieren	Entwicklungsteam kann ohne Code-Release nicht anpassen	Timeouts konfigurierbar machen (z. B. 1,5–5 Sekunden für Transaktionen). Admin-konfigurierbar ist ideal.