REST API-Fehlermeldungen verstehen und beheben

INHALTSVERZEICHNIS

• 1. Grundlagen: HTTP-Statuscodes
• 2. FundraisingBox Error Codes (entscheidend für Debugging)
  • Validierungs- und Eingabefehler
  • Adress- und Kontodaten
  • Duplikate und Zustandskonflikte
  • Datumsbezogene Fehler
  • Berechtigungen & API-Konfiguration
  • Einschränkungen bei Bearbeitung & Löschung
  • SEPA- und Zahlungsfehler
  • Weitere Einschränkungen
  • Technische / globale Fehler
• 3. Zusammenspiel von HTTP-Code und Error Code
• 4. Best Practices für eine stabile Integration
• Zusammenfassung

Bei der Arbeit mit der JSON REST API können verschiedene Fehlermeldungen auftreten. Diese bestehen in der Regel aus zwei Ebenen:

1. HTTP-Statuscode → zeigt die Fehlerkategorie
2. Konkreter Error Code → beschreibt die genaue Ursache

Wenn Sie beide Ebenen richtig interpretieren, können Sie Probleme schnell identifizieren und gezielt beheben.

1. Grundlagen: HTTP-Statuscodes

Die REST API verwendet standardisierte HTTP-Statuscodes:

• 200 → Anfrage erfolgreich
• 4xx → Fehler liegt in Ihrer Anfrage
• 5xx → Fehler liegt auf Serverseite

Die häufigsten Fälle:

• 400: Anfrage ist fehlerhaft (z. B. Validierungsfehler)
• 403: Zugriff verweigert (fehlende User-Rechte auf das Objekt)
• 404: Datensatz nicht gefunden
• 500: Interner Serverfehler

Wichtig: Der HTTP-Statuscode allein reicht nicht aus – die eigentliche Ursache finden Sie im Error Code im Response.

2. FundraisingBox Error Codes (entscheidend für Debugging)

Die FundraisingBox REST API liefert bei Fehlern zusätzliche, strukturierte Fehlercodes im JSON-Response. Diese zeigen Ihnen genau, warum eine Anfrage fehlgeschlagen ist.

Im Folgenden finden Sie die wichtigsten Codes, gruppiert nach Themen.

Validierungs- und Eingabefehler

Diese Fehler treten auf, wenn Daten fehlen, ungültig sind oder nicht den Anforderungen entsprechen.

• required - Ein Pflichtfeld fehlt
• invalid - Ein Wert ist ungültig
• min / max - Wert ist zu niedrig oder zu hoch
• min_length / max_length - Text ist zu kurz oder zu lang
• conflicting_data - Daten sind widersprüchlich
• unknown_field -Feld ist im Schema nicht definiert
• invalid_json - Anfrage enthält kein gültiges JSON

Diese Fehler sind die häufigste Ursache für HTTP 400.

Adress- und Kontodaten

• address_incomplete - Adresse ist unvollständig
• bank_account_incomplete - Bankdaten sind unvollständig

Duplikate und Zustandskonflikte

• already_exists - Objekt existiert bereits
• already_used - Objekt wurde bereits verwendet
• invalid_is_main_status - Es darf nur ein Prio-Wert ("is_main") jeweils pro Adresse / E-Mailadresse / Telefonnummer / Bankkonto am Kontakt existieren

Datumsbezogene Fehler

• date_must_be_future - Datum muss in der Zukunft liegen
• date_must_be_past - Datum muss in der Vergangenheit liegen

Berechtigungen & API-Konfiguration

• no_permission - Keine Berechtigung für diese Aktion
  -> Hier müssen die Nutzerrechte für den genutzten REST API Login und das abzufragende Objekt (z.B. Transaktionen, Spendenaktionen, etc.) angepasst werden
• no_api_package - API-Package ist im Account nicht aktiv (Vertrag prüfen)
• quota_exceeded - Kontingent wurde überschritten
• missing_api_version - API-Version fehlt in der URL
• invalid_api_version - API-Version ist ungültig

Einschränkungen bei Bearbeitung & Löschung

Diese Fehler treten auf, wenn Objekte aufgrund von Abhängigkeiten nicht verändert werden dürfen.

• not_editable - Feld ist nicht editierbar
• not_deletable - Objekt kann nicht gelöscht werden
• donations_exist - Verknüpfte Spenden vorhanden
• recurrings_exist - Verknüpfte wiederkehrende Zahlungen vorhanden
• donations_or_recurrings_exist - Kombination aus Beidem vorhanden
• fundraising_pages_exist - Verknüpfte Spendenaktions-Seiten vorhanden
• project_items_exist - Projekt wird noch verwendet
• has_receipt - Spende mit bereits erstellter Spendenbescheinigung kann nicht gelöscht werden

Diese Fehler sind typisch bei Delete- oder Update-Requests.

SEPA- und Zahlungsfehler

• missing_sepa_config - Um SEPA-Lastschriften zu nutzen, müssen Sie zuvor in Ihrer FundraisingBox einige SEPA-Angaben wie die Gläubiger-ID angeben (unter Account > SEPA Details)
• sepa_mandate_payment_type_mismatch - Entweder verwenden Sie eine Zahlungsart, für die kein SEPA-Mandat erforderlich ist, oder eine Zahlungsart, für die ein SEPA-Mandat erforderlich ist, verfügt über kein solches. Beispielsweise eine PayPal-Spende mit SEPA-Mandat oder eine SEPA-Lastschrift-Spende ohne SEPA-Mandat.
• reference_prefix_invalid - Die angegebene SEPA-Mandatsreferenz darf nicht mit einer bestimmten Zeichenfolge beginnen
• signature_dispensable - Ein noch ausstehendes SEPA-Mandat darf kein Unterschriftsdatum enthalten

Weitere Einschränkungen

• no_square_size - Bild muss quadratisch sein
• person_on_waitlist - Kontakt befindet sich auf der Warteliste, daher ist diese Aktion für den Kontakt nicht erlaubt (auf den Kontakt bestehen daher technisch keine Schreibrechte aktuell, bis dieser von der Warteliste übernommen wurde)
• vbpk_exists - Änderungen wegen existierender vbPK nicht möglich (nur für Kund*innen aus Österreich mit aktivierter BMF Schnittstelle relevant)

Technische / globale Fehler

Diese betreffen die gesamte Anfrage, nicht einzelne Felder:

• missing_id - Eine benötigte ID fehlt
• no_write_operation_available - Objekt ist read-only
• unknown_error - Unbekannter Fehler

3. Zusammenspiel von HTTP-Code und Error Code

Für die Fehleranalyse ist die Kombination entscheidend:

• HTTP 400 + required → Pflichtfeld fehlt
• HTTP 400 + invalid → Wert ist falsch
• HTTP 403 + no_permission → keine Berechtigung
• HTTP 404 → Objekt existiert nicht

Der HTTP-Code zeigt Ihnen die Richtung, der Error Code die konkrete Ursache.

4. Best Practices für eine stabile Integration

Damit Fehler möglichst selten auftreten und schnell gelöst werden können:

• Implementieren Sie Validierung vor dem API-Call
• Loggen Sie Requests und Responses vollständig
• Werten Sie Error Codes systematisch im Code aus
• Nutzen Sie Retry-Mechanismen
• Testen Sie Integrationen zunächst in einer sicheren Umgebung, z.B. einem Testaccount

Zusammenfassung

Die REST API setzt auf ein klares und effektives Fehlersystem:

• HTTP-Statuscodes geben die grobe Richtung vor
• Error Codes liefern die genaue Ursache

Wenn Sie beide Ebenen kombinieren und die konkreten Error Codes aktiv auswerten, können Sie Fehler schnell beheben und Ihre Integration deutlich robuster gestalten.