Fehlerbehandlung & HTTP-Statuscodes – aifinyo | Billomat

Wenn eine API-Anfrage nicht klappt, sagt dir der HTTP-Statuscode genau, woran es liegt – und wie du das Problem behebst.

Wie funktioniert die Fehleranzeige?

Jede Antwort der Billomat API enthält einen HTTP-Statuscode – eine dreistellige Zahl, die anzeigt, ob die Anfrage erfolgreich war oder nicht. Erfolgreiche Antworten beginnen mit 2xx, Fehler mit 4xx (Problem auf deiner Seite) oder 5xx (Problem auf Billomat-Seite).

Zusätzlich zum Statuscode enthält der Response-Body bei Fehlern immer eine Klartextmeldung, die den Fehler genauer beschreibt:

<?xml version="1.0" encoding="UTF-8"?>
<errors>
<error>Resource not found</error>
</errors>

Eselsbrücke:
4xx = Das Problem liegt bei dir – falsche Daten, fehlender Schlüssel, keine Berechtigung.
5xx = Das Problem liegt bei Billomat – der Server hat einen Fehler gemacht.

Erfolgscodes (2xx)

Code	Name	Bedeutung	Wann?
`200 OK`	OK	Alles hat funktioniert ✅	GET, PUT, DELETE
`201 Created`	Created	Datensatz erfolgreich erstellt ✅	POST

Fehlercodes (4xx) – Problem auf deiner Seite

Code	Name	Bedeutung	Typische Ursache
`400`	Bad Request	Anfrage war fehlerhaft	Ungültige oder fehlende Pflichtfelder, falsches Datenformat
`401`	Unauthorized	Nicht authentifiziert	API-Schlüssel fehlt, ist falsch oder der API-Zugriff ist nicht aktiviert
`403`	Forbidden	Zugriff verweigert	Der Benutzer hat keine Berechtigung für diese Aktion
`404`	Not Found	Nicht gefunden	Falsche URL, falsche Ressource oder ID existiert nicht
`429`	Too Many Requests	Zu viele Anfragen	API-Kontingent für dieses Zeitfenster erschöpft

Serverfehlercodes (5xx) – Problem auf Billomat-Seite

Code	Name	Bedeutung	Was tun?
`500`	Internal Server Error	Interner Fehler auf Billomat-Seite	Anfrage nach kurzer Wartezeit wiederholen; bei Häufung Support kontaktieren
`503`	Service Unavailable	Dienst vorübergehend nicht verfügbar	Wartungsarbeiten oder temporäre Überlast – etwas warten und erneut versuchen

Die häufigsten Fehler und wie du sie behebst

401 – Unauthorized

Der häufigste Fehler beim Einstieg. Checkliste:

Ist der API-Schlüssel korrekt kopiert – ohne Leerzeichen am Anfang oder Ende?
Ist der API-Zugriff für diesen Benutzer unter Einstellungen > Mitarbeiter aktiviert?
Wird der Schlüssel korrekt übergeben – per Header X-BillomatApiKey oder GET-Parameter api_key?
Bei registrierten Apps: Werden X-AppId und X-AppSecret ebenfalls mitgeschickt?

400 – Bad Request

Die Anfrage war fehlerhaft. Häufige Ursachen:

Ein Pflichtfeld fehlt – z.B. client_id beim Erstellen einer Rechnung.
Ein Feldwert hat das falsche Format – z.B. Datum als 31.12.2024 statt 2024-12-31.
Der Content-Type-Header stimmt nicht mit dem gesendeten Format überein.
Der Request-Body ist kein valides XML oder JSON – z.B. ein fehlendes schließendes Tag.

Tipp: Lies die Fehlermeldung im Response-Body genau – sie enthält oft einen konkreten Hinweis auf das fehlerhafte Feld, z.B.:

<error>client_id is required</error>

404 – Not Found

Der angeforderte Datensatz existiert nicht. Mögliche Ursachen:

Die ID in der URL ist falsch oder der Datensatz wurde gelöscht.
Der Ressourcenname ist falsch geschrieben – z.B. /api/invoice statt /api/invoices (Plural beachten!).
Die billomatID in der URL ist falsch.

429 – Too Many Requests

Das API-Kontingent für das aktuelle Zeitfenster ist erschöpft. Die Fehlermeldung enthält die Wartezeit:

<errors>
<error>Maximum number of requests reached. Try again in 246 seconds.</error>
</errors>

Warte die angegebene Zeit ab und versuche es dann erneut. Mehr zum Thema Kontingente und wie du sie optimierst, erfährst du im Artikel Rate Limiting & Zugriffsbegrenzung.

Empfehlungen für die Fehlerbehandlung in eigenen Anwendungen

Wenn du eine eigene Anwendung auf Basis der Billomat API entwickelst, solltest du Fehler systematisch behandeln:

Immer den Statuscode prüfen – nicht nur auf eine erfolgreiche Antwort hoffen.
Fehlermeldung aus dem Body auslesen und loggen – das spart Stunden bei der Fehlersuche.
Bei 5xx-Fehlern automatisch wiederholen – z.B. nach 5, 30 und 60 Sekunden (exponentielles Backoff).
Bei 429 die Wartezeit respektieren – sofortiges Wiederholen führt nur zu weiteren 429-Fehlern.
Bei 401 nie automatisch wiederholen – zuerst die Ursache beheben (API-Schlüssel prüfen).

Nächste Schritte

Rate Limiting & Zugriffsbegrenzung – wie das API-Kontingent funktioniert und wie du es optimal einsetzt
Tools & Testing – wie du Fehler schnell mit Postman oder curl eingrenzt

Verknüpfung mit