API-Sicherheit, Rate Limits, Idempotenz und Support

Produktive Integrationen sollten API-Schlüssel schützen, Berechtigungen minimieren und jeden Retry deterministisch behandeln.

API-Schlüssel schützen#

• Speichern Sie mm_live_…-, mm_test_…- und whsec_…-Secrets ausschließlich serverseitig in einer Secret-Verwaltung.
• Legen Sie getrennte Schlüssel pro Umgebung und Integration an.
• Gewähren Sie nur benötigte Scopes und setzen Sie bei zeitlich begrenzten Integrationen ein Ablaufdatum.
• Rotieren oder widerrufen Sie Schlüssel sofort bei Verdacht auf Offenlegung oder bei einem Ownership-Wechsel.
• Übertragen Sie Schlüssel nie in URLs, Client-Bundles, Logs oder Support-Tickets.

Rate Limits und Fehlerbehandlung#

• Live-Schlüssel erlauben 600 Requests pro Minute; Testschlüssel 120 Requests pro Minute.
• Beachten Sie X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset.
• Bei 429 enthält die Antwort zusätzlich Retry-After.
• Wiederholen Sie Netzwerkfehler, 408, 425, 429 und 5xx mit begrenztem exponentiellem Backoff und Jitter.
• Wiederholen Sie andere 4xx-Antworten erst, nachdem Request, Scope oder Berechtigung korrigiert wurde.

Idempotenz#

POST /partner/v1/deliveries und POST /partner/v1/fleet/orders benötigen einen Idempotency-Key.

• Verwenden Sie pro fachlichem Auftrag einen stabilen, eindeutigen Schlüssel.
• Derselbe Schlüssel mit identischem Body gibt die ursprüngliche Ressource mit 200 und Idempotent-Replayed: true zurück.
• Derselbe Schlüssel mit verändertem Body wird mit 409 idempotency_key_reused abgelehnt.
• Test- und Live-Modus verwenden getrennte Idempotenz- und external_id-Namensräume.

Technischen Support beschleunigen#

Senden Sie bei Problemen Endpunkt, HTTP-Methode, request_id, Zeitstempel, Modus, Statuscode und eine bereinigte Payload. Entfernen Sie API-Schlüssel, Webhook-Secrets, personenbezogene Daten und andere vertrauliche Inhalte.