API-Fehlerbehandlung: HTTP-Statuscodes und Fehlermeldungen

Die Faktoora API gibt bei Problemen standardisierte HTTP-Statuscodes und aussagekräftige Fehlermeldungen zurück. Dieser Artikel hilft Ihnen, häufige Fehler zu verstehen und zu beheben.

HTTP 404: Rechnung nicht gefunden

Wenn Sie versuchen, eine Rechnung über die API abzurufen oder zu ändern und eine 404-Fehlermeldung erhalten, bedeutet dies, dass die angeforderte Ressource nicht gefunden wurde.

Häufige Ursachen:

• Fehlerhafte faktooraId: Überprüfen Sie, dass Sie die korrekte faktooraId verwenden. Diese wurde bei der Rechnungserstellung im Response unter faktooraId übergeben.
• Asynchrone Rechnungserstellung: Wenn Sie unmittelbar nach der Erstellung eine Rechnung mit GET abrufen möchten, kann eine 404 auftreten. Die API antwortet auf POST-Requests mit 202 Accepted und einer faktooraId. Die Rechnung wird asynchron verarbeitet und kann kurzzeitig nicht abrufbar sein. Verwenden Sie den angegebenen faktooraId zum Abrufen des Status oder nutzen Sie Webhooks für Benachrichtigungen, wenn die Verarbeitung abgeschlossen ist.
• Rechnung wurde gelöscht: Die angeforderte Rechnung existiert nicht mehr im System.

Lösung:

Validieren Sie die faktooraId in Ihrem Request. Für neu erstellte Rechnungen: Warten Sie einige Sekunden oder prüfen Sie den Verarbeitungsstatus mit GET /invoices/{faktooraId}/status, bevor Sie auf den vollständigen Invoice-Datensatz zugreifen.

HTTP 400: Fehlerhafte Anfrage

Ein HTTP-400-Fehler signalisiert ein Validierungsproblem im angeforderten Request. Dies ist der häufigste Fehler bei der API-Integration.

Fehlerhafte oder fehlende Pflichtparameter

Ursachen:

• Pflichtfelder fehlen (z. B. invoiceNumber, issueDate, buyer, seller)
• Feld-Formate sind falsch (z. B. Datum nicht im Format YYYYMMDD)
• Unbekannte oder ungültige Werte für enumerierte Felder (z. B. invoiceTypeCode)

Lösung:

Prüfen Sie die API-Dokumentation oder das OpenAPI-Schema auf erforderliche Felder und deren gültige Wertebereiche. Der Error-Response enthält Hinweise auf das fehlerhafte Feld.

Validierungsfehler bei Dezimalzahlen: "must be multiple of 0.01"

Wenn Sie Beträge im allowance-Array (Rabatte oder Zuschläge) oder anderen Geldfeldern übermitteln, müssen alle Dezimalzahlen auf maximal 2 Dezimalstellen begrenzt sein.

Fehler tritt auf bei:

• allowance[].amount mit mehr als 2 Dezimalstellen (z. B. 10.005 statt 10.00)
• Ähnliche Probleme mit anderen Geldwertfeldern

Lösung:

Runden Sie alle Geldbeträge auf 2 Dezimalstellen. Beispiel:

{
  "allowance": [
    {
      "indicator": "discount",
      "reason": "Mengenrabatt",
      "amount": 10.50,
      "taxes": [
        {
          "typeCode": "VAT",
          "categoryCode": "S",
          "rate": 19
        }
      ]
    }
  ]
}

HTTP 400: "Docx template is disabled"

Diese Fehlermeldung bedeutet, dass Sie versucht haben, bei der Rechnungserstellung ein DOCX- oder Typst-Template zu verwenden, aber die Templating-Funktion nicht aktiviert ist.

Ursachen:

• Ihr Konto hat die Templating-Funktionen nicht aktiviert
• Sie übergeben das Feld template im Request, obwohl die Funktion nicht freigeschaltet ist

Lösung:

Es gibt zwei Möglichkeiten:

1. Template-Feld weglassen: Entfernen Sie das template-Objekt aus dem Request, um die Standard-Rechnungsvorlage zu verwenden.
2. Funktion aktivieren: Kontaktieren Sie den Faktoora Support, um die Templating-Funktionen (DOCX- oder Typst-Templating) für Ihr Konto freizuschalten.

Wenn die Funktionen aktiviert sind, können Sie mit dem template.label-Parameter den Namen Ihrer benutzerdefinierten Vorlage angeben.

Allowance wird nicht im PDF angezeigt

Wenn Sie allowance-Daten in der API übergeben, diese aber nicht im generierten Rechnungs-PDF erscheinen oder nicht von der Gesamtsumme abgezogen werden, können mehrere Ursachen vorliegen.

Häufige Ursachen:

• Fehlende Steuersätze: Jeder Allowance-Eintrag erfordert ein taxes-Array mit mindestens einem VAT-Eintrag. Ohne korrekte Steuerkonfiguration wird die Allowance unter Umständen ignoriert.
• Rechnungsformat unterstützt keine Allowances: Nicht alle Rechnungsformate (z. B. einfache PDF-Rechnungen im simple-Format) unterstützen Allowances. Allowances werden in den strukturierten Formaten (ZUGFeRD, XRechnung) korrekt verarbeitet.

Lösung:

Stellen Sie sicher, dass:

1. Jeder Allowance-Eintrag ein taxes-Array mit mindestens einem Eintrag enthält:

"taxes": [
  {
    "typeCode": "VAT",
    "categoryCode": "S",
    "rate": 19
  }
]

2. Sie ein strukturiertes Rechnungsformat verwenden, das Allowances unterstützt (format: "zf:2" oder format: "xrechnung").

HTTP 500: Interner Serverfehler

Ein 500-Fehler bedeutet, dass auf dem Server ein unerwarteter Fehler aufgetreten ist. Der Fehler Cannot read properties of undefined ist ein Hinweis auf einen Null-Pointer-ähnlichen Fehler im Code.

Häufige Ursachen:

• Ungültige oder inkonsistente Datenstrukturen: Felder sind vorhanden, aber deren Inhalte erfüllen Erwartungen nicht.
• Fehlende erforderliche Verkettungen: Wenn Sie ein Objekt referenzieren (z. B. einen Kunden über buyer.faktooraCustomerId), wird die Referenz möglicherweise nicht aufgelöst.
• Temporärer Fehler: Gelegentliche 500er können auch technische Ausfallzeiten des Servers bedeuten.

Lösung:

1. Überprüfen Sie Ihren Request auf Vollständigkeit und Gültigkeit — insbesondere Verweise auf externe Ressourcen (Kunden-IDs, Template-IDs).
2. Versuchen Sie den Request nach kurzer Zeit erneut.
3. Wenn der Fehler persistiert, kontaktieren Sie den Faktoora Support mit Details zu:
   • Der genauen API-Anfrage (ohne Schlüssel oder sensible Daten)
   • Den Zeitstempel des Fehlers
   • Die Antwort oder Fehlermeldung, die Sie erhalten haben

Best Practices für fehlerfreie API-Integration

• Validieren Sie lokal: Prüfen Sie Ihre Daten, bevor Sie sie an die API schicken — Formate, Pflichtfelder, Längenbeschränkungen.
• Nutzen Sie das Demo-Environment: Testen Sie zuerst gegen https://api.demo.faktoora.com/api/v1 statt gegen die Produktivumgebung https://api.faktoora.com/api/v1.
• Behandeln Sie asynchrone Verarbeitung: Rechnungserstellung ist asynchron. Rufen Sie nicht unmittelbar danach den Status ab, sondern nutzen Sie Webhooks oder Polling mit einem Abstand.
• Antworten protokollieren: Speichern Sie die vollständige API-Antwort, besonders bei 400er- und 500er-Fehlern — sie enthält den Hinweis auf das fehlerhafte Feld.
• Dokumentation prüfen: Die OpenAPI-Dokumentation enthält alle Anforderungen für jeden Endpunkt.