Express Kurier. Direkt.
Auch Overnight.
x25pronto Schweiz bringt Ware direkt ans Ziel. Für kleine Ware fährt ein Auto. Für mehr Platz gibt es Transporter oder XL. Direkt, Express und Overnight fahren von Montag bis Sonntag. Freie Zeiten stehen im Kalender.
Idempotenz, Retries und Rate‑Limiting bei Kurier‑APIs
Wie Sie Doppelbuchungen vermeiden, sinnvolle Retry‑Strategien und Backoff einsetzen und Rate‑Limits im Betriebsalltag von Kurier‑APIs handhaben.
Kurzantwort
Kurz: Verhindern Sie Doppelbuchungen mit Idempotency‑Keys, verwenden Sie abgestufte Retry‑Strategien mit exponentialem Backoff und planen Sie für Rate‑Limit‑Responses (HTTP 429) ein. So bleiben Buchungen konsistent und Ihr Betriebsablauf in Zürich, Basel oder Genf stabil.
Warum Idempotenz wichtig ist
Bei Kurierbuchungen kann ein mehrfach gesendeter Request zu Doppelbuchungen führen. Das kostet Zeit und erzeugt Verwirrung beim Dispo in Zürich oder beim Fahrer. Idempotenz macht wiederholte Requests sicher: Ein einmal verarbeiteter Intent wird nicht erneut ausgeführt. Geschäftskritische Aktionen sind so vor Mehrfachausführung geschützt.
Idempotency‑Keys: Praxisregeln
Vergeben Sie für jede intentionale Handlung einen eindeutigen Idempotency‑Key. Der Key sollte vom Client erzeugt werden (z. B. UUID v4). Bewahren Sie diesen Key mit der Buchungsreferenz in Ihrer Datenbank. Akzeptieren Sie gleiche Keys innerhalb einer definierten Zeitspanne (z. B. 24 Stunden) als identisch. Dokumentieren Sie in der Integration, ob die Kurier‑API den Key erwartet und wie lange sie eine Idempotency‑History speichert.
Retries: Wann und wie oft neu versuchen
Retries sind nötig bei transienten Fehlern: Netzwerkabbrüche, Timeouts oder kurzzeitige Serverprobleme. Keine Retries bei Clientfehlern (HTTP 4xx ausser 429). Setzen Sie eine Begrenzung (z. B. maximal 3–5 Versuche). Nutzen Sie idempotente Endpunkte oder Idempotency‑Keys, bevor Sie automatisch wiederholen. Loggen Sie jeden Versuch für Audits.
Backoff‑Strategien: Exponential Backoff mit Jitter
Exponential Backoff erhöht die Wartezeit zwischen Versuchen exponentiell (z. B. 1s, 2s, 4s). Fügen Sie Jitter (zufällige Abweichung) hinzu, um Synchronisations‑Spitzen zu vermeiden. Beispiel: base=500ms, multiplier=2, jitter=random(−250..+250)ms. So reduzieren Sie Lastspitzen auf der Kurier‑API und die Chance auf erneute 429‑Antworten.
Rate‑Limit‑Handling im Tagesbetrieb
API‑Provider signalisieren Limits oft per HTTP Header (z. B. X-RateLimit-Remaining, Retry-After). Reagieren Sie auf 429 mit respektvollem Backoff und informieren Sie Ihre Disposition, falls Buchungen verzögert werden. Implementieren Sie eine zentrale Request‑Queue in Ihrem System, die Workloads steuert und Prioritäten (z. B. Eilgüter vs. Standard) erlaubt.
Monitoring, Alerts und Fallbacks
Messen Sie Fehlerraten, Latenzen und abgewiesene Requests. Richten Sie Alerts bei anhaltendem Anstieg von 5xx oder 429 ein. Definieren Sie Fallbacks: Retry später automatisch, informieren manuelle Dispo‑Punkte oder bieten Sie dem Nutzer eine Bestätigung, dass die Buchung in Prüfung ist. Nutzen Sie Transaktionslogs, um bei Inkonsistenzen schneller zu entschlüsseln, was passiert ist.
Häufige Fragen
Was ist ein Idempotency‑Key und wer erstellt ihn?
Ein Idempotency‑Key ist ein eindeutiger Bezeichner für eine gewünschte Aktion. Er wird meist vom Client (Ihr ERP oder Webportal) erzeugt und an die Kurier‑API übergeben. So erkennt der Provider wiederholte Requests als identisch.
Wie reagiere ich auf einen HTTP 429 (Too Many Requests)?
Lesen Sie den Retry‑After Header. Starten Sie einen Backoff, erhöhen Sie die Wartezeit bei weiteren 429‑Antworten und legen Sie die Anfrage in eine Queue. Informieren Sie erforderliche Personen, wenn Verzögerungen kritisch sind.
Dürfen alle Endpunkte einfach wiederholt werden?
Nein. Lesen Sie die API‑Dokumentation. Nur idempotente Endpunkte oder solche mit Idempotency‑Key sind sicher wiederholbar. Vermeiden Sie automatische Retries bei nicht‑idempotenten Aktionen ohne Absicherung.
Wie lange soll ich Idempotency‑Keys speichern?
Das hängt von Prozessen ab. Viele Systeme speichern Keys 24–72 Stunden. Entscheiden Sie basierend auf Stornofristen und Auditanforderungen.