Reference

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:

json
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

400
Bad Request

Ungültige Request-Daten (JSON, XML, fehlende Pflichtfelder)

401
Unauthorized

Fehlender oder ungültiger API Key

402
Payment Required

Kontingent aufgebraucht, Upgrade erforderlich

403
Forbidden

API Key hat keine Berechtigung für diese Ressource

404
Not Found

Ressource (z.B. Invoice) nicht gefunden

422
Unprocessable Entity

Semantischer Fehler (z.B. ungültige USt-IdNr.)

429
Too Many Requests

Rate Limit erreicht

500
Internal Server Error

Serverfehler, bitte erneut versuchen

503
Service Unavailable

Service temporär nicht verfügbar (Wartung)

API Error Codes

CodeHTTPBeschreibungLösung
INVALID_REQUEST400Request-Body ist kein gültiges JSON oder XMLÜberprüfe die Syntax deines Request-Bodys
MISSING_FIELD400Ein Pflichtfeld fehlt im RequestFüge das fehlende Feld hinzu (siehe details.field)
INVALID_FORMAT400Das angegebene Format wird nicht unterstütztNutze: xrechnung-3.0, zugferd-2.1, etc.
VALIDATION_FAILED400E-Rechnung entspricht nicht dem SchemaPrüfe die details für spezifische Fehlermeldungen
UNAUTHORIZED401API Key fehlt oder ist ungültigPrüfe den Authorization: Bearer <key> Header
INVALID_API_KEY401API Key existiert nicht oder wurde widerrufenErstelle einen neuen API Key im Dashboard
QUOTA_EXCEEDED402Monatliches Kontingent aufgebrauchtUpgrade deinen Plan oder warte bis zum Monatsende
FORBIDDEN403API Key hat keine BerechtigungPrüfe, ob der Key für diesen Endpoint freigeschaltet ist
NOT_FOUND404Ressource nicht gefundenPrüfe die ID oder den Endpoint-Pfad
INVALID_VAT_ID422USt-IdNr. hat falsches FormatFormat: DE + 9 Ziffern (z.B. DE123456789)
INVALID_LEITWEG422Leitweg-ID hat falsches FormatFormat: XXX-XXXXX-XX (z.B. 991-12345-67)
INVALID_IBAN422IBAN ist ungültigPrüfe die IBAN-Prüfsumme
CALCULATION_MISMATCH422Summen stimmen nicht übereinPrüfe: Netto + MwSt = Brutto
RATE_LIMITED429Zu viele AnfragenWarte und versuche es später erneut
INTERNAL_ERROR500Interner ServerfehlerVersuche 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-01

Eine Rechnung muss eine Leitweg-ID enthalten

Feld: buyer.leitweg

BR-DE-15

Ländercode des Verkäufers muss übermittelt werden

Feld: seller.address.country

BR-DE-17

USt-IdNr. oder Steuernummer des Verkäufers fehlt

Feld: seller.vatId / seller.taxNumber

BR-16

Rechnungssumme stimmt nicht mit Positionen überein

Feld: totals / items

BR-CO-10

Summe der Positionen ungleich Rechnungsnetto

Feld: items[].quantity * items[].unitPrice

BR-CO-13

MwSt-Betrag stimmt nicht mit Steuersatz überein

Feld: vat calculation

BR-S-08

Ungültiger MwSt-Kategoriecode

Feld: items[].vat

BR-CL-10

Ungültiger Währungscode

Feld: currency

Vollständige Liste: KoSIT XRechnung Spezifikation

Retry-Strategie

Implementiere Retries für temporäre Fehler (429, 5xx):

typescript
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 retry
15 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 backoff
22 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 error
30 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.