Zum Hauptinhalt springen

Troubleshooting-Guide: finway Expense Export API

Dieser Leitfaden deckt alle typischen Fehlerquellen, HTTP-Statuscodes und Stolperfallen bei der Anbindung der finway Expense Export API ab. Er richtet sich an Entwickler und Integratoren.

Verfasst von Enrico Hartwich

1. Technischer Ablauf des Export-Prozesses

Die finway Expense Export API arbeitet asynchron in vier aufeinanderfolgenden Phasen:

  1. Export anstoßen (POST /v1/exports/expenses): Startet den Export und gibt sofort den HTTP-Status 202 Accepted mit einer exportId zurück.

  2. Status abfragen (GET /v1/exports/expenses/{exportId}): Polling des Jobs (Status: pending → processing → done oder failed).

  3. Download-URL abrufen (GET /v1/exports/expenses/{exportId}/download): Sobald der Status done ist, liefert dieser Endpunkt eine temporäre, signierte URL.

  4. Datei abrufen: Download des ZIP-Archivs über die signierte URL und anschließendes Entpacken der enthaltenen CSV-Datei.

2. Authentifizierung & Autorisierung (HTTP 401 & 403)

HTTP 401 Unauthorized – "You are not authorized"

  • Ursache 1: Fehlendes oder fehlerhaftes Bearer-Präfix
    ​    Die API verwendet den HTTP-Header Authorization: Bearer <api-key>. Wenn lediglich der Key ohne das Wort Bearer oder als generischer Header (z. B. finway Auth: ... oder x-api-key: ...) übergeben wird, verweigert der Server den Zugriff.

  • Lösung: Authentifizierungsmethode Bearer Auth wählen und ausschließlich den Key hinterlegen. Falls Header Auth genutzt wird, muss der Name exakt Authorization lauten und der Wert als Bearer fwk_live_... formatiert sein.

  • Ursache 2: Ungültiger, abgelaufener oder unvollständiger API-Key
    ​    Der API-Key muss stets mit dem Präfix fwk_live_ beginnen. Häufig werden beim Kopieren führende oder nachfolgende Leerzeichen übernommen, oder es wurde ein alter Key verwendet.

  • Lösung: Unter finway → Systemeinstellungen → API-Keys einen neuen Key generieren, auf Vollständigkeit prüfen und ohne Leerzeichen einfügen.

HTTP 403 Forbidden – "companyId is not in the API key's allowed set"

  • Ursache: Fehlende Mandantenberechtigung
    ​    Der API-Key ist gültig, hat jedoch keinen Zugriff auf die im Body angefragte companyId, oder das Unternehmen wurde in fiinway deaktiviert/gelöscht.

  • Lösung: Prüfen, in welchem Mandanten / welcher Organisation der API-Key erstellt wurde. Der Key muss für die im Request angegebene companyId freigeschaltet sein.

3. Datenvalidierung & Request-Body (HTTP 400 & 422)

HTTP 400 Bad Request – "companyId must be a valid id"

  • Ursache: Falsches ID-Format
    ​    Die Unternehmens-ID muss genau 24 Zeichen enthalten und darf nur aus Buchstaben und Zahlen bestehen. Wird ein anderes Format verwendet, beispielsweise eine reine Zahlen-ID (z. B. 8529374848), tritt ein Fehler auf.

  • Lösung:

    1. In finway im Webbrowser anmelden.

    2. Die URL in der Adresszeile prüfen: [https://app.finway.de/company/](https://app.finway.de/company/)<24-stellige-ID>/....

    3. Die Unternehmens-ID kopieren

HTTP 400 Bad Request – Datumsvalidierung (from / to)

  • Ursache: Falsches Datumsformat
    ​    Die Felder from und to müssen dem Standard ISO 8601 für reine Datumsangaben (YYYY-MM-DD) entsprechen (z. B. "2026-01-01"). Formate wie DD.MM.YYYY, MM/DD/YYYY oder Unix-Timestamps werden abgewiesen.

  • Lösung: Datumsangaben vor dem API-Call stets in das Schema YYYY-MM-DD umformatieren.

HTTP 400 Bad Request – Ungültige exportId beim Polling oder Download

  • Ursache: Die in den Pfadparametern übergebene exportId entspricht nicht dem geforderten 24-stelligen Hex-Format.

  • Lösung: Bitte stellen Sie sicher, dass Sie exakt die exportId übergeben, die von der POST-Anfrage zurückgegeben wurde.

HTTP 422 Unprocessable Entity – "Export size limit exceeded"

  • Ursache: Datenmenge zu groß
    ​    Im angeforderten Zeitraum befinden sich zu viele Ausgaben für einen einzelnen Exportlauf.

  • Lösung: Den Datumsbereich aufteilen (z. B. monatlich oder quartalsweise statt über ein ganzes Jahr) und mehrere Exporte sequenziell anstoßen.

4. Fehlende Daten & Nicht gefundene Ressourcen (HTTP 404)

HTTP 404 bei POST /v1/exports/expenses

  • Ursache 1: Das Unternehmen existiert nicht im Mandanten.

  • Ursache 2: Im gewählten Zeitraum (from bis to) existieren keine Ausgaben, die den Kriterien entsprechen.

  • Lösung: Prüfen, ob für das gewählte Leistungsdatum (datePurchased) im finway-Portal Belege vorhanden sind. Falls auch archivierte Belege exportiert werden sollen, den Parameter "includeArchived": true im Request-Body ergänzen.

HTTP 404 bei GET /v1/exports/expenses/{exportId}

  • Ursache: Die exportId existiert nicht oder ist einem anderen Mandanten bzw. einem Unternehmen zugeordnet, auf das Sie mit Ihrem API-Schlüssel keinen Zugriff haben.

  • Lösung: Überprüfen, ob die ID unverändert aus dem Initialaufruf durchgereicht wird.

HTTP 404 bei GET /v1/exports/expenses/{exportId}/download

  • Ursache: Vorzeitiger Download-Aufruf
    ​    Der Download-Endpunkt wurde aufgerufen, während sich der Exportauftrag noch im Status pending oder processing befand. Dieser Fehler kann auch auftreten, wenn der Exportauftrag fehlgeschlagen ist, da die Datei in beiden Fällen nicht zum Download bereitsteht.

  • Lösung: Die Download-URL darf erst abgerufen werden, wenn die Statusabfrage explizit status: "done" zurückgibt. Eine Kontrollweiche (z. B. ein IF-Node) vor den Download-Schritt schalten.

5. Parallelität & Rate Limits (HTTP 429)

HTTP 429 bei POST /v1/exports/expenses – Gleichzeitiger Export

  • Ursache: Für dieselbe companyId darf maximal ein Export gleichzeitig aktiv sein. Startet ein zweiter Export, während der vorherige noch läuft, antwortet die API mit HTTP 429.

  • Lösung:

    • Den Response-Header Retry-After auswerten.

    • In Automations-Tools sicherstellen, dass Workflows für dasselbe Unternehmen strikt sequenziell ausgeführt werden und nicht parallel triggern.

HTTP 429 bei Status- oder Download-Aufrufen – Polling Rate Limit

  • Ursache: Das Polling-Limit liegt bei maximal 1 Request pro Sekunde pro Mandant (geteilt über Status- und Download-Endpunkte).

  • Lösung:

    • Das Polling-Intervall auf einen festen Wert von mindestens 5 Sekunden einstellen (z. B. über einen "Wait"-Node).

    • Bei Erhalt eines 429-Fehlers die im Header Retry-After angegebene Wartezeit pausieren.

6. Download- und Verarbeitungsfehler

Fehler beim Download über die downloadUrl (S3 / Storage)

  • Problem 1: Authorization-Header beim Datei-Download
    ​    Wird beim HTTP-Request auf die downloadUrl der finway-Bearer-Token mitgesendet, verweigert der Cloud-Storage-Dienst den Zugriff.

    • Lösung: Der Download-Request muss als einfacher GET-Request ohne Authorization-Header ausgeführt werden, da die signierte URL bereits temporäre Zugangsdaten enthält. Unter Authentication None wählen.

  • Problem 2: Signierte URL ist abgelaufen
    ​    Die über /download bereitgestellte URL besitzt eine kurze Gültigkeitsdauer (expiresAt).

    • Lösung: Die Datei unmittelbar nach Erhalt der URL herunterladen. Bei Verzögerungen muss der Endpunkt /download erneut aufgerufen werden, um eine frische URL zu generieren.

Verarbeitungsfehler beim Einlesen: "Invalid CSV"

  • Ursache: Die API liefert unter der Download-URL kein reines CSV, sondern ein komprimiertes ZIP-Archiv (finwayExport_<timestamp>.zip), in dem sich die eigentliche CSV-Datei befindet.

  • Lösung: Die heruntergeladene Binärdatei muss im Workflow zuerst über einen ZIP-/Decompress-Schritt entpackt werden, bevor der CSV-Parser auf die enthaltene Datei zugreift.

7. Asynchrone Verarbeitungsfehler (Status failed)

Wenn der Status-Endpunkt 200 OK liefert, der Payload jedoch "status": "failed" enthält, ist der Export auf Serverseite fehlgeschlagen:

JSON

{

"exportId": "507f1f77bcf86cd799439012",

"status": "failed",

"createdAt": "2026-06-12T10:00:00.000Z",

"error": "Export failed"

}


​Lösung:

  1. Das Feld error im JSON-Response protokollieren.

  2. Den Export mit einem engeren Datumsbereich erneut versuchen.

  3. Bleibt der Fehler bestehen, den finway-Support kontaktieren und die exportId sowie den Zeitstempel angeben.

8. Übersicht der HTTP-Statuscodes

Statuscode

Endpunkt

Typische Ursache

Behebung

202 Accepted

POST /v1/exports/expenses

Export erfolgreich gestartet.

exportId speichern und Polling beginnen.

400 Bad Request

Alle

Ungültige Parameter (z. B. companyId keine 24-Hex-ID, falsches Datumsformat).

Unternehmens-ID aus der URL koperien (Nach /company/

401 Unauthorized

Alle

Header fehlt, kein Bearer-Präfix, falscher/abgelaufener Key.

Authorization: Bearer fwk_live_... prüfen.

403 Forbidden

POST /v1/exports/expenses

API-Key besitzt keine Berechtigung für diese companyId.

API-Key im richtigen Mandanten ausstellen bzw. Company-Berechtigung prüfen.

404 Not Found

POST

Keine Ausgaben im Zeitraum vorhanden.

Datumsfilter anpassen oder includeArchived: true setzen.

404 Not Found

GET .../download

Export ist noch in Bearbeitung (pending/processing).

Erst abrufen, wenn Statusabfrage done meldet.

422 Unproc. Entity

POST

Export-Größenlimit überschritten.

Datumsbereich verkürzen.

429 Too Many Req.

POST

Für die Company läuft bereits ein Export.

Warten bis der laufende Job beendet ist (Retry-After beachten).

429 Too Many Req.

GET (Status/Download)

Polling-Rate überschritten (> 1 Request/Sekunde).

Polling-Intervall auf mindestens 5 Sekunden erhöhen.

Verwandte Artikel
Hat dies deine Frage beantwortet?