Fünf kritische Fehler bei der API-Integration beim Start

Fehler Nummer 1. Keine Idempotenz und „Sturm“ der Retrays

Symptome: doppelte Bestellungen/Zahlungen, Diskrepanz der Beträge, umstrittene Retouren, DLQ-Alerts steigen.

Die Wurzel: Redelivering Requests/Webhooks und Netzwerk-Flappies sind normal. Wenn die Operation „Erstellen/Abschreiben“ nicht idempotent ist, multiplizieren die Retrays den Schaden.

Wie es richtig ist

Idempotency-Key/' operation _ id 'auf alle unsicheren Methoden (POST/PATCH).

Eindeutiger Index in der DB durch 'operation _ id'. Wiederholen - Geben Sie das vorherige Ergebnis zurück.

Webhooks über die Inbox-Tabelle (dedupe durch 'event _ id + signature'). Ausgehende Ereignisse sind Outbox.

Retrays: maximal 1-2 mal, Aussteller + Jitter, nur für sicheren Betrieb.

HTTP-Konvention (Beispiel):

http
POST /v1/payments
Idempotency-Key: ik_f35a2
Content-Type: application/json

{"amount": 5000, "currency": "EUR", "source": "card_..."}

SQL-Schutz (vereinfacht):

sql
ALTER TABLE payments ADD CONSTRAINT uniq_op UNIQUE (operation_id);

Retrays mit Jitter (Pseudocode):

python for i in range(2):
try: return call_api(payload, timeout=0. 6)
except Timeout:
sleep(0. 05 2i + random. uniform(0, 0. 05))
raise UpstreamUnavailable

Checkliste:

Die gesamte „Geld/erschaffende“ Logik hat eine „operation _ id“ und einen uniq-Index.
Eingehende Webhooks nur über Inbox mit einem idempotenten Worker.
Das Client SDK legt automatisch einen Idempotency-Key ab.

Fehler Nummer 2. Timeouts/Retrays vs. SLO: Abhängigkeiten „überhitzen“

Symptome: p95 schwimmt plötzlich weg, die Warteschlangen wachsen, der Kreisverkehrsbrecher „knallt“.

Wurzel: Die allgemeine SLO der Antwort beträgt 400-600 ms, und die Timeouts zu externen APIs betragen 1-2 s und sogar Retrays × 3. Sie machen länger als Sie können und stürmen die Sucht mit Wiederholungen.

Wie es richtig ist

Budget-Timing: wenn SLO 400 ms, Upstream-Timeout: 250-300 ms; Allgemeine Zeitüberschreitung der Anforderung ≤ SLO.

Limits/Backpressure: Semaphore/Worker-Pool für Anrufe zu jeder Abhängigkeit. Überfüllt → 429/503 sofort.

Circuit Breaker: 'open' bei Timeouts/5xx, 'half-open' dosiert.

Zugriffskontrolle: Begrenzung der Parallelität (pro Stream, pro Endpunkt/PSP).

Beispiel (Go):

go sem: = make (chan struct {}, 64 )//competition limit to PSP func callPSP (ctx context. Context, req Req) (Res, error) {
select {
case sem <- struct{}{}:
defer func(){ <-sem }()
c, cancel:= context. WithTimeout(ctx, 300time. Millisecond)
defer cancel()
return psp. Do(c, req)
default:
return Res {}, ErrBusy//sofortiger Ausfall statt Warteschlange ohne Ende
}
}

Checkliste:

Timeouts sind kürzer als SLO; Retrai ≤ 2; Es gibt einen Jitter.
Pools/Semaphoren zu externen APIs; Circuit Breaker mit Metriken.
Auf „busy“ -Routen geben wir 429/Retry-After zurück, anstatt Verbindungen zu halten.

Fehler Nummer 3. Schwache Sicherheit: Webhook-Signaturen, Geheimnisse, TLS

Symptome: „Fremde“ Webhooks passieren, Geheimnisse im Code/Log, MITM-Risiken.

Wurzel: Keine Signatur-/Frischeprüfung, Geheimnisse leben in env-Dateien, alten TLS und schwachen Überschriften.

Wie es richtig ist

Signatur Webhooks HMAC-SHA256 + 'X-Timestamp' (Fenster ≤ 5-10 min), strikter Vergleich der Signatur.

mTLS für kritische Integrationen oder IP allow-list.

Rotation der Geheimnisse über Vault/Cloud KMS; ein Minimum an Rechten; Prüfung der Subtraktion.

TLS 1. 2/1. 3 nur, HSTS, korrekte CORS (enge Quellenliste).

Signaturprüfung (Python):

python def verify(sig_hdr, ts_hdr, body, secret):
if abs(time. time() - int(ts_hdr)) > 600: raise Expired()
calc = hmac. new(secret, (ts_hdr + "." + body). encode(), hashlib. sha256). hexdigest()
if not hmac. compare_digest(calc, sig_hdr): raise BadSig()

Checkliste:

Alle Webhooks sind signiert und verifiziert; Das Frischefenster ist begrenzt.
Geheimnisse in KMS/Vault, es gibt Rotation und Audit.
TLS/HSTS enthalten; CORS Punkt; IP/mTLS wo relevant.

Fehler Nr. 4. Vertragsdrift: Schema „lebte sein eigenes Leben“

Symptome: Prod fiel „nur bei einem Teil der Kunden“, 500/422 in den Protokollen, verschiedene SDK-Versionen und APIs streiten.

Wurzel: keine strenge Beschreibung der Verträge, umgekehrt inkompatible Änderungen, „stille“ Felder, unterschiedliche Bedeutungen der gleichen Namen.

Wie es richtig ist

Vertrag: OpenAPI/AsyncAPI + Server/Client-Generierung; für Veranstaltungen - Avro/Protobuf + Schema Registry.

Versionierung: „v1 → v2“ (URI/Header), Deprection-Plan, Grace-Periode.

Backward-compat: nur additive Änderungen in Moll-Releases; Verbot des Löschens/Umbenennens ohne v-Bump.

Vertragstests: Pact/Buf - Provider/Consumer werden im CI geprüft.

Beispiele:

yaml
OpenAPI: Ein eindeutiger Summentyp in kleinen Einheiten amount_minor:
type: integer minimum: 0 description: Summe in minimalen Währungseinheiten (integer)

Checkliste:

Verträge werden in git gespeichert, CI validiert/bricht bei Inkompatibilität.
Schemaregister für Ereignisse, Kompatibilität „back/forward“.
Änderungsdockingseite, Entbehrungstermine, Partnerprüfstand.

Fehler Nummer 5. „Blind“ -Start: keine Metriken/Logs/Traces und Sandbox

Symptome: „nichts zu sehen“, Unterstützung überfordert, debag - mit den Händen im Produkt.

Wurzel: Nicht enthalten Beobachtbarkeit, keine Synthetik, Sandkasten getestet „in Worten“.

Wie es richtig ist

RED/USE-Metriken: rate/error/latency auf jedem Endpoint, nach Routen/Methoden.

Korrelation: 'trace _ id' in allen Protokollen und Antworten; Bündel von zapros↔vebkhuk.

Synthetik: Gesundheitsproben (Login/Deposit-Sand), SLA-Überwachung T + 60 für Webhooks.

Sandbox/Stage: vollständig isolierte Schlüssel/Domains, fiktive PSPs, Einträge „fallen nicht in die Berichte“.

Antwort mit Trace-ID:

http
HTTP/1. 1 202 Accepted
Trace-Id: 7f2b3d8e9c1a4
Location: /v1/ops/req_42/status

Checkliste:

RED/USE Metriken, Dashboards, Alerts (Symptome + Ursachen).
End-to-End-Traces; JSON-Logs, ohne PII, mit 'trace _ id'.
Kunststoffe aus Schlüsselregionen; Sandkasten ist obligatorisch, die Schlüssel sind unterschiedlich.

Vorlaunchplan (T-7 → T-0)

T-7 Tage:

Abschließender Vertragsscan: Gibt es inkompatible Änderungen? Freeze-Schaltungen.
Geheimnisse/Zertifikate: Überprüfen Sie Rotation, Zugriffe, KMS-Richtlinien.
24 × 7 Synthetik, Alerts sind an On-Call gebunden.

T-3 Tage:

Belastung Mini-Run (Burst 2-5 min): p95/Pools/Warteschlangen im grünen Bereich.
DRY-RUN Webhooks (Wiederholungen, 5xx, Jitter), DLQ-Prüfung.
„Buch der Telefone“ Partner: L1/L2 Kontakte, War-Room-Kanal.

T-0:

Kanarischer Verkehr 5% → 25% → 50% auf SLO-Gates; fertig rollback.
Kill-Switch/Feature-Flags auf Risiko-Fics enthalten.
Der Kriegsraum ist aktiv, die Statusvorlagen sind vorbereitet.

Rollback-Plan (wenn etwas schief gegangen ist)

1. Nehmen Sie Verkehr auf die vorherige stabile Version/Route.

2. Deaktivieren Sie umstrittene Änderungen mit Ficheflag.

3. Stabilisieren Sie Warteschlangen/Pools, stoppen Sie Retrays bei „Sturm“.

4. Post-Incident: Zeitlinie, Wurzeln, Aufgaben (Fix-Forward/Vertragsfixes) sammeln.

Launch-Selbsttest-Tabelle (kurz)

Block	Die Frage	Ja/Nein
Idempotenz	Haben alle „erstellenden“ Methoden einen Idempotency-Key/' operation _ id 'und einen uniq-Index?
Retrays/Auszeiten	Timeouts sind kürzer als SLO; Retrai der ≤2; Ist Jitter an?
Sicherheit	Webhooks signiert, Frischefenster ≤10 Minuten, Geheimnisse im KMS?
Verträge	OpenAPI/AsyncAPI fest, CI fängt Inkompatibilität?
Beobachtungsstand	ROT/USE, Trails, Synthetik T + 60, Sandkasten isoliert?
Rollback	Gibt es einen Rollback/Kill-Switch-Button, einen Kommunikationsplan?

Häufig gestellte Fragen „Was ist, wenn...?“

... der Anbieter Idempotency-Key nicht unterstützt?

Speichern Sie' hash (body)'+ 'partner _ request _ id' und geben Sie Ihre Idempotenz ein.

... Webhooks manchmal „vor“ der Antwort kommen?

Nähen Sie „operation _ id“ und behalten Sie vorübergehend den Status „unknown → reconcile“ bei. periodischer Reconciler schließt die Varianzen.

... man alte und neue Kunden unterstützen muss?

Versionieren Sie Endpoint's ('/v1 'und '/v2'), leiten Sie über den Header/URI, halten Sie die Backward-Kompatibilität für mindestens N Monate.

Zusammenfassung

Bei Integrationsversagen geht es fast immer um dasselbe: keine Idempotenz, falsche Auszeiten und Retrays, schwache Webhook-Signatur, Vertragsdrift und fehlende Sichtbarkeit. Verträge vorab fixieren, Beobachtbarkeit ermöglichen, Limits/Bexpresher setzen, alle externen Interaktionen unterschreiben und Synthetik starten. Dann bleibt Ihre Veröffentlichung auch bei Störungen bei Partnern überschaubar - ohne Geld, das in den Retrays verloren geht, und ohne eine schlaflose Nacht für das gesamte Team.