bexio-Schnittstelle meldet 400 oder 422

Ein 400 bedeutet laut der bexio-API-Dokumentation, dass die Anfrageparameter ungültig sind. Ein 422 heisst, dass die Entität nicht gespeichert werden konnte, meist wegen einer Validierung. Prüfen Sie dann die Pflichtfelder, die Formate und bei Adressen die getrennten Felder für Strasse und Hausnummer. Die Dokumentation zum jeweiligen Endpunkt zeigt, was dort verlangt wird.

Symptome erkennen

Ursachen und Lösungen in Prüfschritten

1. Antwort lesen. Der Fehlertext hat die Form eines JSON-Objekts mit error_code und message. Notieren Sie beides. Es hilft bei der eigenen Fehlersuche und bei einer Meldung an bexio.
2. Header und Format prüfen. Jede Anfrage braucht «Accept: application/json» und «Authorization: Bearer <token>». Bei Anfragen mit Inhalt kommt Content-Length hinzu. Senden Sie den Inhalt als JSON. Verwenden Sie die HTTP-Methode, die beim Endpunkt steht. Die Dokumentation nennt GET zum Lesen, POST zum Erstellen, PATCH für Änderungen mit Teildaten und PUT für Änderungen mit vollständigen Daten. Ältere Endpunkte ändern Einträge teilweise per POST.
3. Pflichtfelder vergleichen. Beim Anlegen eines Kontakts sind laut Dokumentation contact_type_id (1 für Firma, 2 für Person), name_1, user_id und owner_id Pflicht. Prüfen Sie für jeden Endpunkt die als «required» markierten Felder.
4. Abhängige Felder beachten. Ob ein Feld erlaubt oder nötig ist, hängt manchmal von anderen Werten oder von Einstellungen ab. Ein Beispiel: Die Dokumentnummer document_nr darf bei Verkaufsdokumenten nicht mitgesendet werden, wenn die automatische Nummerierung aktiv ist. Ist sie ausgeschaltet, ist die Nummer Pflicht. Die Einstellung finden Sie bei den Standardeinstellungen der Dokumenttypen, wie Nummernkreise und Dokumentnummern in bexio einstellen zeigt.
5. Strukturierte Adressen übernehmen. Kontakte und Zusatzadressen kennen street_name, house_number und address_addition. street_name ist Pflicht, sobald house_number oder address_addition gesetzt sind, und house_number und address_addition setzen street_name voraus. Das frühere Feld address ist in Anfragen veraltet und kommt nur noch in Antworten vor. Senden Sie also Strasse und Hausnummer getrennt. Hintergrund und Umstellung beschreibt Strukturierte Adressen umstellen.
6. Werte und Längen prüfen. Preise und Mengen erlauben höchstens 6 Nachkommastellen. Beim Endpunkt für ausgehende Zahlungen von Einkaufsrechnungen gelten Längen wie 70 Zeichen für den Empfängernamen, 255 für die Strasse, 10 für die Hausnummer und 50 für den Ort. Der Betrag erlaubt höchstens zwei Dezimalstellen. Die Hausnummer ist bei IBAN- und QR-Zahlungen Pflicht. Die IBAN muss gültig sein, bei QR-Zahlungen eine QR-IBAN. Das Ausführungsdatum darf bei IBAN und QR nicht in der Vergangenheit und nicht auf einem Wochenende liegen. Es darf auch nicht in ein geschlossenes oder gesperrtes Geschäftsjahr fallen.
7. Referenzierte IDs prüfen. Felder wie user_id, contact_id oder tax_id verweisen auf bestehende Objekte. Die Dokumentation beschreibt, wie Sie gültige Steuersätze über die Schnittstelle abrufen. Verwenden Sie nur IDs, die es in Ihrem Konto gibt.
8. Grenzen beachten. Die Dokumentation empfiehlt, beim Erstellen von Verkaufsdokumenten höchstens 150 Positionen mitzusenden und weitere über den Endpunkt für Positionen zu ergänzen. Bei Listen ist der Parameter limit auf 2000 begrenzt, der Standard liegt bei 500.
9. Kleinste Anfrage testen. Reproduzieren Sie den Fehler in einem Werkzeug wie Postman mit einer minimalen Anfrage und fügen Sie Felder schrittweise hinzu, bis der Fehler wieder erscheint.

Bei Zapier und Make

Zapier hat die bexio-Integration in Version 4.0.8 auf strukturierte Adressen umgestellt. Das Adressfeld ist weggefallen und durch «Street Name», «House Number» und «Address Addition» ersetzt worden. Bestehende Abläufe müssen die Felder entsprechend zuordnen. Öffnen Sie den Zap mit «Edit Zap», wählen Sie die bexio-Aktion oder den Trigger und bestätigen Sie die Update-Benachrichtigung. Testen Sie danach mit «Test trigger». Wenn das Kontofeld leer ist, verbinden Sie das Konto erneut. Mehr dazu steht in Zapier-Verbindung zu bexio erneuern. Nutzen Sie ein anderes Werkzeug wie Make, prüfen Sie, ob dessen bexio-Modul die neuen Adressfelder anbietet, und passen Sie die Zuordnung an.

Wann der bexio-Support weiterhilft

Die Schnittstelle wird laut Dokumentation ohne geführte Einrichtung und ohne Code-Support bereitgestellt. Lässt sich ein Fehler mit einem Testwerkzeug reproduzieren, melden Sie ihn über das Formular «Report a problem» der Dokumentation. Beschreiben Sie die Schritte genau und geben Sie keine Zugangsdaten an. Für fertige Anbindungen von Drittanbietern wenden Sie sich laut bexio-Hilfe an den Anbieter. Zum Einstieg in die Schnittstelle dient bexio-API: erste Schritte.

Häufige Fragen

Was ist der Unterschied zwischen 400 und 422?

Ein 400 meldet ungültige Anfrageparameter. Ein 422 meldet, dass die Entität nicht gespeichert werden konnte, etwa wegen einer Validierungsregel.

Warum scheitert meine Adresse, obwohl sie früher funktionierte?

Weil Strasse und Hausnummer inzwischen getrennte Felder sind und das alte Feld address in Anfragen als veraltet gilt. Senden Sie street_name, house_number und address_addition.

Darf ich die Dokumentnummer immer mitsenden?

Nein. Bei aktiver automatischer Nummerierung ist sie nicht erlaubt, bei ausgeschalteter Nummerierung ist sie Pflicht.

Fazit

Bei 400 und 422 lohnt sich ein ruhiger Vergleich der Anfrage mit der Dokumentation des Endpunkts: Header, Pflichtfelder, abhängige Felder, Formate und Adressen. Die Fehlermeldung nennt den Ausgangspunkt, eine minimale Testanfrage grenzt die Ursache ein. Bei Zapier genügt oft das Aktualisieren der Integration und das Neuzuordnen der Adressfelder.