Error Handling
Verstehe API-Fehler und lerne, wie du sie in deiner Anwendung behandelst. Alle Fehler folgen einem einheitlichen Format mit hilfreichen Details.
Error Response Format
Alle API-Fehler werden im folgenden JSON-Format zurückgegeben:
1{2 "error": "VALIDATION_FAILED",3 "message": "Die Rechnung entspricht nicht dem XRechnung 3.0.2 Schema"4}error
Maschinenlesbarer Fehlercode zum programmatischen Handling
message
Menschenlesbare Fehlerbeschreibung
HTTP Status Codes
Ungültige Request-Daten (JSON, XML, fehlende Pflichtfelder)
Fehlender oder ungültiger API Key
Kontingent aufgebraucht, Upgrade erforderlich
API Key hat keine Berechtigung für diese Ressource
Ressource (z.B. Invoice) nicht gefunden
Semantischer Fehler (z.B. ungültige USt-IdNr.)
Rate Limit erreicht
Serverfehler, bitte erneut versuchen
Service temporär nicht verfügbar (Wartung)
API Error Codes
| Code | HTTP | Beschreibung | Lösung |
|---|---|---|---|
INVALID_REQUEST | 400 | Request-Body ist kein gültiges JSON oder XML | Überprüfe die Syntax deines Request-Bodys |
MISSING_FIELD | 400 | Ein Pflichtfeld fehlt im Request | Füge das fehlende Feld hinzu (siehe details.field) |
INVALID_FORMAT | 400 | Das angegebene Format wird nicht unterstützt | Nutze: xrechnung-3.0, zugferd-2.1, etc. |
VALIDATION_FAILED | 400 | E-Rechnung entspricht nicht dem Schema | Prüfe die details für spezifische Fehlermeldungen |
UNAUTHORIZED | 401 | API Key fehlt oder ist ungültig | Prüfe den Authorization: Bearer <key> Header |
INVALID_API_KEY | 401 | API Key existiert nicht oder wurde widerrufen | Erstelle einen neuen API Key im Dashboard |
QUOTA_EXCEEDED | 402 | Monatliches Kontingent aufgebraucht | Upgrade deinen Plan oder warte bis zum Monatsende |
FORBIDDEN | 403 | API Key hat keine Berechtigung | Prüfe, ob der Key für diesen Endpoint freigeschaltet ist |
NOT_FOUND | 404 | Ressource nicht gefunden | Prüfe die ID oder den Endpoint-Pfad |
INVALID_VAT_ID | 422 | USt-IdNr. hat falsches Format | Format: DE + 9 Ziffern (z.B. DE123456789) |
INVALID_LEITWEG | 422 | Leitweg-ID hat falsches Format | Format: XXX-XXXXX-XX (z.B. 991-12345-67) |
INVALID_IBAN | 422 | IBAN ist ungültig | Prüfe die IBAN-Prüfsumme |
CALCULATION_MISMATCH | 422 | Summen stimmen nicht überein | Prüfe: Netto + MwSt = Brutto |
RATE_LIMITED | 429 | Zu viele Anfragen | Warte und versuche es später erneut |
INTERNAL_ERROR | 500 | Interner Serverfehler | Versuche es erneut, kontaktiere Support bei Wiederholung |
XRechnung Validierungsfehler (BR-DE)
Diese Fehler stammen aus der KoSIT-Schematron-Validierung und werden in error.details zurückgegeben:
BR-DE-01Eine Rechnung muss eine Leitweg-ID enthalten
Feld: buyer.leitweg
BR-DE-15Ländercode des Verkäufers muss übermittelt werden
Feld: seller.address.country
BR-DE-17USt-IdNr. oder Steuernummer des Verkäufers fehlt
Feld: seller.vatId / seller.taxNumber
BR-16Rechnungssumme stimmt nicht mit Positionen überein
Feld: totals / items
BR-CO-10Summe der Positionen ungleich Rechnungsnetto
Feld: items[].quantity * items[].unitPrice
BR-CO-13MwSt-Betrag stimmt nicht mit Steuersatz überein
Feld: vat calculation
BR-S-08Ungültiger MwSt-Kategoriecode
Feld: items[].vat
BR-CL-10Ungültiger Währungscode
Feld: currency
Vollständige Liste: KoSIT XRechnung Spezifikation
Retry-Strategie
Implementiere Retries für temporäre Fehler (429, 5xx):
1async function createInvoice(data, retries = 3) {2 for (let i = 0; i < retries; i++) {3 try {4 const response = await fetch('https://api.invoice.xhub.io/api/v1/invoice/DE/XRECHNUNG/generate', {5 method: 'POST',6 headers: {7 'Authorization': 'Bearer sk_live_...',8 'Content-Type': 'application/json'9 },10 body: JSON.stringify(data)11 });12 13 if (response.status === 429) {14 // Rate limited - wait and retry15 const retryAfter = response.headers.get('Retry-After') || 60;16 await new Promise(r => setTimeout(r, retryAfter * 1000));17 continue;18 }19 20 if (response.status >= 500) {21 // Server error - retry with exponential backoff22 await new Promise(r => setTimeout(r, Math.pow(2, i) * 1000));23 continue;24 }25 26 const result = await response.json();27 28 if (!response.ok) {29 // Client error - don't retry, handle the error30 throw new Error(result.message);31 }32 33 return result;34 } catch (error) {35 if (i === retries - 1) throw error;36 }37 }38}Best Practices
Fehler loggen
Logge immer die requestId mit. So können wir bei Support-Anfragen den Request nachvollziehen.
Retry nur bei 5xx/429
Client-Fehler (4xx) werden durch Retries nicht behoben. Nur bei Server- oder Rate-Limit-Fehlern macht Retry Sinn.
Exponential Backoff
Bei Retries: Verdopple die Wartezeit nach jedem Fehlversuch (1s, 2s, 4s, ...), um den Server nicht zu überlasten.
Retry-After Header
Bei 429 enthält der Header Retry-After die empfohlene Wartezeit in Sekunden.
Support
Bei wiederkehrenden Fehlern oder unklaren Fehlermeldungen kontaktiere uns unter support@xhub.io mit der requestId.