Fehlerbehandlung und Retry-Strategie in der Produktion

Der Rechnungsversand darf nicht stillstehen, wenn ein einzelner Call scheitert.

Vorgehen

  1. 1

    5xx und Zeitüberschreitungen wiederholen, mit exponentiell wachsender Wartezeit.

  2. 2

    4xx NICHT wiederholen — ein Validierungsfehler wird durch Wiederholen nicht richtig. Beleg zur Prüfung markieren.

  3. 3

    Bei 429 die Kontingentgrenze respektieren und den Versand verzögern statt abzubrechen.

  4. 4

    Den Fehlercode mitloggen. Häufen sich dieselben Codes, ist die Ursache meist eine Stelle in Ihren Stammdaten.

Der Aufruf

POST /api/v1/invoice/DE/xrechnung/generate

bash
1curl -X POST https://api.invoice-api.xhub.io/api/v1/invoice/DE/xrechnung/generate \
2  -H "X-API-Key: $INVOICE_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5  "invoice": {
6    "invoiceNumber": "RE-2025-004",
7    "type": "invoice",
8    "issueDate": "2025-01-15",
9    "dueDate": "2025-02-15",
10    "currency": "EUR",
11    "seller": {
12      "name": "Muster GmbH",
13      "vatId": "DE811128135",
14      "street": "Musterstraße 1",
15      "postalCode": "10115",
16      "city": "Berlin",
17      "countryCode": "DE",
18      "email": "info@muster.de",
19      "phone": "+49 30 12345678"
20    },
21    "buyer": {
22      "name": "Beispiel AG",
23      "vatId": "DE136695976",
24      "street": "Beispielweg 42",
25      "postalCode": "80331",
26      "city": "München",
27      "countryCode": "DE"
28    },
29    "items": [
30      {
31        "position": 1,
32        "description": "Beratungsleistung",
33        "quantity": 10,
34        "unit": "HUR",
35        "unitPrice": 150,
36        "taxRate": 19,
37        "netAmount": 1500,
38        "taxAmount": 285,
39        "grossAmount": 1785
40      }
41    ],
42    "taxSummary": [
43      {
44        "taxRate": 19,
45        "netAmount": 1500,
46        "taxAmount": 285
47      }
48    ],
49    "subtotal": 1500,
50    "total": 1785,
51    "countrySpecific": {
52      "countryCode": "DE",
53      "leitwegId": "991-12345-67"
54    }
55  }
56}'

Wo es schiefgeht

Ein blinder Retry über alle Fehlerarten hinweg erzeugt Doppelrechnungen. Nur wiederholen, was durch Wiederholen besser werden kann.

FehlerreferenzBestehende Rechnung prüfen, bevor sie rausgeht

Weitere Rezepte