Fehler 429 und 500 bei der bexio-Schnittstelle

Ein 429 bedeutet laut der bexio-API-Dokumentation, dass ein Unternehmen das Limit der Anfragen pro Minute erreicht hat. Senden Sie weniger Anfragen und setzen Sie nach der Wartezeit fort, die der Header RateLimit-Reset in Sekunden nennt. Ein 500 meldet einen unerwarteten Zustand auf Seiten der Schnittstelle. Prüfen Sie dann die Statusseite von bexio und wiederholen Sie die Anfrage mit Abstand.

Symptome erkennen

Ursachen und Lösungen bei 429

1. Header auslesen. Die Schnittstelle sendet RateLimit-Limit (aktuelles Limit der Periode), RateLimit-Remaining (verbleibende Anfragen) und RateLimit-Reset (verbleibende Zeit bis zur nächsten Periode in Sekunden). Protokollieren Sie diese Werte. So sehen Sie, wie nah Ihre Anbindung am Limit arbeitet.
2. Ablauf stoppen und warten. Pausieren Sie, bis die in RateLimit-Reset genannte Zeit abgelaufen ist, und setzen Sie dann fort. Wiederholen Sie bei einem 429 nicht sofort in Dauerschleife, sonst bleiben Sie im Limit hängen.
3. Weniger Anfragen senden. Das Limit gilt laut Dokumentation pro Unternehmen. Prüfen Sie deshalb, ob mehrere Anbindungen oder Abläufe gleichzeitig laufen. Rufen Sie Listen mit dem Parameter limit ab, statt Einträge einzeln zu holen. Der Standard liegt bei 500, das Maximum bei 2000. Zum Anlegen vieler Kontakte gibt es einen Endpunkt zum gebündelten Erstellen. Statt jeden Datensatz einzeln anzulegen, sparen Sie so Anfragen.
4. Läufe verteilen. Legen Sie grosse Abgleiche nicht in eine einzelne Minute, sondern verteilen Sie sie über längere Zeit. In Zapier oder Make helfen Pausen zwischen den Schritten und zeitversetzte Starts. Das ist eine praktische Empfehlung und keine Vorgabe aus der bexio-Dokumentation.
5. Wiederholung planen. Wiederholen Sie bei einem 429 nach der Wartezeit. Für Schreibzugriffe empfiehlt sich eine Kontrolle, ob der Eintrag schon angelegt wurde, damit keine Dubletten entstehen. Auch das ist eine Empfehlung.

Ursachen und Lösungen bei 500

1. Statusseite prüfen. Unter bexio-status.com zeigt bexio den Zustand der Dienste, darunter die API und das Banking. Dort sehen Sie laufende und gelöste Störungen. Per E-Mail, Atom- oder RSS-Feed lassen sich Meldungen abonnieren. Die API-Dokumentation weist ebenfalls darauf hin, dass die Statusseite über kurzfristige Probleme informiert.
2. Anfrage mit Abstand wiederholen. Ein 500 meldet einen unerwarteten Zustand. Treten Fehler nur zeitweise auf, wiederholen Sie die Anfrage nach einer Pause. Verlängern Sie die Pausen bei jedem Versuch. Ein 503 verweist auf Wartungsarbeiten, hier hilft Warten.
3. Fehler eingrenzen. Wiederholt sich ein 500 bei derselben Anfrage, prüfen Sie, ob nur bestimmte Daten ihn auslösen. Reproduzieren Sie den Fehler mit einem Testwerkzeug wie Postman und einer minimalen Anfrage. Prüfen Sie auch, ob die Anfrage selbst fehlerhaft ist. Dafür gibt es die Codes 400 und 422, siehe bexio-Schnittstelle meldet 400 oder 422. Zugriffsfehler behandelt bexio-Schnittstelle meldet 401 oder 403.
4. Fehler melden. Bleibt der 500 reproduzierbar, melden Sie ihn über das Formular «Report a problem» der Dokumentation. Beschreiben Sie die Schritte so, dass bexio sie nachstellen kann, und geben Sie keine Zugangsdaten an.

Störungen erkennen und im Betrieb überwachen

Wer die Schnittstelle produktiv nutzt, sollte Fehler nicht erst bemerken, wenn ein Kunde nachfragt. Richten Sie eine Benachrichtigung ein, die bei Fehlerantworten anschlägt, und abonnieren Sie die Statusseite von bexio. Halten Sie fest, welche Abläufe laufen und wann, damit Sie bei Störungen wissen, was nachzuholen ist. Eine kurze Checkliste für den Betrieb:

• Statuscode, Zeitpunkt und Endpunkt jedes Fehlers protokollieren.
• Die Werte aus RateLimit-Remaining und RateLimit-Reset mitschreiben.
• Die Zahl der Wiederholungen begrenzen und danach melden, statt endlos weiterzuversuchen.
• Nach einer Störung prüfen, ob Einträge fehlen oder doppelt entstanden sind.
• Die Statusseite von bexio abonnieren. Praktische Hinweise finden Sie in Automatisierungen überwachen. Einen Überblick über das, was die Schnittstelle leistet, bietet Die bexio-Schnittstelle: was damit möglich ist.

Wann der bexio-Support weiterhilft

Die API wird laut Dokumentation so bereitgestellt, wie sie beschrieben ist. Es gibt keine geführte Einrichtung und keinen Code-Support. Bei einem reproduzierbaren Fehler nutzen Sie das Formular der Dokumentation. Verwenden Sie eine fertige Anbindung eines Drittanbieters, wenden Sie sich laut bexio-Hilfe an den Anbieter, denn bexio unterstützt Partner-Anbindungen nicht.

Häufige Fragen

Wie viele Anfragen sind pro Minute erlaubt?

Die Dokumentation nennt im Abschnitt zur Begrenzung keine feste Zahl. Das aktuelle Limit steht im Header RateLimit-Limit jeder Antwort.

Soll ich einen 500 sofort wiederholen?

Warten Sie kurz und versuchen Sie es mit grösserem Abstand erneut. Dauert der Fehler an, prüfen Sie die Statusseite.

Ist 503 dasselbe wie 500?

Nein. 503 bedeutet laut Dokumentation, dass der Server wegen Wartungsarbeiten nicht verfügbar ist. 500 meldet einen unerwarteten Zustand.

Fazit

Ein 429 verlangt weniger und besser verteilte Anfragen, ein 500 vor allem Geduld, einen Blick auf die Statusseite und eine saubere Wiederholung. Lesen Sie die RateLimit-Header, planen Sie Pausen ein und melden Sie reproduzierbare Fehler über das Formular der Dokumentation.