Idempotenzschlüssel

Neue logische Operation → neue zufällige UUID. Wiederholung oder Wiederherstellung derselben Operation → derselbe gespeicherte Schlüssel und dieselbe vollständige Anfrage. Eine bewusste erneute Auswertung identischer Eingaben ist eine neue Operation, keine Wiederholung. Ein Operationsschlüssel erlaubt einem HTTP- oder SDK-Client, ein erfolgreiches Ergebnis nach einer verlorenen Antwort ohne weitere Auswertung oder Abbuchung wiederherzustellen, innerhalb des Aufbewahrungsfensters. Diese Regeln gelten für die gehostete API und das Sitzungs-Playground, nicht allgemein für eigenständige SDK-Adapter oder direkte Anbieter.

Bereit für Fragen

Q: Was ist ein Idempotenzschlüssel in der System One API? A: Ein clientseitig erzeugtes Token. Retries liefern dasselbe Entscheidungsergebnis und belasten Credits nicht doppelt.

Q: Wann senden? A: Immer wenn derselbe logische Aufruf nach Timeout, Netzwerkfehler oder 5xx erneut versucht werden kann.

Einen Schlüssel pro Operation speichern

Senden Sie für jede Operation einen Idempotency-Key-Header. Erzeugen Sie die UUID einmal, vor dem ersten Versand, und bewahren Sie sie zusammen mit der vollständigen Anfrage auf. Verwenden Sie keinen globalen Umgebungsschlüssel, keine von Jobs geteilte Konstante und keinen Content-Hash: identischer Inhalt kann zu getrennten abrechnungspflichtigen Auswertungen gehören. Schlüssel sind 1–128 Zeichen lang, beginnen mit einem Buchstaben oder einer Ziffer und erlauben danach Buchstaben, Ziffern, Punkte, Unterstriche, Doppelpunkte und Bindestriche.

Für eine Wiederholung verwenden Sie dasselbe operation-Objekt aus dem gehosteten Schnellstart. Dieser Ausschnitt ersetzt dessen evaluate()-Aufruf und verwendet dessen client wieder; er erzeugt keine Operation und keine UUID:

const result = await client.evaluate(operation.request, {
  maxRetries: 0,
  timeoutMs: 30_000,
  headers: { 'Idempotency-Key': operation.idempotencyKey },
});

Der Schnellstart hält die Operation nur im Speicher. Jeder Skriptlauf erzeugt eine neue abrechnungspflichtige Operation, und ist keine neustartsichere Wiederherstellung. In einer echten Anwendung speichern Sie die gesamte Operation — Schlüssel und vollständige Anfrage einschließlich des gewählten Modells — im Job-Datensatz vor dem ersten Versand dauerhaft. Laden Sie nach einem Absturz diesen Datensatz, statt eine UUID zu erzeugen oder die Anfrage neu zu bauen. Halten Sie bei einem Retry im Prozess das bestehende Objekt und wiederholen Sie nur den Aufruf, nachdem Sie den aufgezeichneten Ausgang behandelt haben. Erzeugen Sie im Retry-Code keinen frischen Schlüssel: das kann eine weitere Abbuchung erzeugen.

Die HTTP-Referenz zeigt den entsprechenden Header in einem curl-Request. Weder das SDK noch sein Fetch-Transport erzeugt automatisch einen Idempotenzschlüssel.

Die Anfrage unverändert lassen

Schlüssel sind auf ein Konto bezogen, über alle seine API-Schlüssel und sein Sitzungs-Playground hinweg. Andere Konten haben getrennte Namensräume. Ein anderer gültiger API-Schlüssel desselben Kontos kann eine Operation wiederherstellen; ein widerrufener Schlüssel kann sie nicht authentifizieren. API-Schlüssel erwerben keine Berechtigung für sitzungsgebundene Endpunkte.

Der Dienst vergleicht die validierte kanonische Anfrage einschließlich ihres effektiven Modells, Kontexts, Fragen, Kriterien und akzeptierten Erweiterungsfelder. Formatierungsleerzeichen und die Reihenfolge der Objektschlüssel sind unerheblich. Die Reihenfolge von Arrays, die Reihenfolge der Score-Rubrik, Feldwerte sowie null gegenüber weggelassenen Feldern sind relevant. Eine andere Anfrage unter demselben Schlüssel liefert 409 idempotency_conflict.

Senden und speichern Sie immer eine explizite model-ID aus der aktuellen Modellliste. Ein weggelassenes Modell wird vor dem Vergleich auf den Dienststandard aufgelöst. Explizite Aliase und Versionsnamen bleiben Teil der Anfrageidentität, auch wenn zwei Namen dasselbe Modell auflösen. Ersetzen Sie bei der Wiederherstellung nicht die angeforderte ID durch das aufgelöste Modell der Antwort. Hat eine frühere Anfrage ihr Modell weggelassen, behalten Sie das ursprüngliche effektive Modell, wenn sich der Standard ändert; prüfen Sie die ursprüngliche Operation, bevor Sie eine Wiederherstellung versuchen.

Exakte Dezimalidentität bleibt erhalten: 9007199254740993 unterscheidet sich von 9007199254740992, und 1e-400 unterscheidet sich von null. Äquivalente Dezimalschreibweisen vergleichen gleich, doppelte Objektschlüssel werden abgelehnt, einschließlich maskierter äquivalenter Namen. Dies vergleicht das auf der Leitung eingereichte JSON; es kann keine bereits in Ihrem numerischen Typ verlorene Präzision wiederherstellen. Bewahren Sie bei Bedarf den ursprünglichen JSON-Text auf. Ein anderes Modell oder eine andere Rubrik ist eine neue Operation und kann einen anderen Preis haben; ein erfolgreicher Replay des Originals berechnet trotzdem null.

Bilder sind Teil der vollständigen Anfrageidentität, einschließlich jedes base64-Strings, Medientyps, jeder Darstellung und der Array-Reihenfolge. Ein Umstellen oder Ersetzen eines Bildes unter demselben aufbewahrten Schlüssel kollidiert; ein Wechsel zwischen Data-URL und Objekt ist kein transparenter Retry. images: [] ist für reine Textmodelle gültig, aber nicht identisch mit dem Weglassen des Feldes. Bewahren Sie für die Wiederherstellung den ursprünglichen Body auf, statt Dateien neu zu kodieren oder ihn aus dem aktuellen Playground-Zustand neu zu bauen.

Dem aufgezeichneten Ausgang folgen

Ein erfolgreicher Replay enthält X-Idempotency-Replayed: true, X-System-One-Credits: 0 und die ursprüngliche X-Request-Id; ursprüngliche Tracking-Header des Modelldienstes bleiben erhalten, wenn verfügbar. Er verwendet die gespeicherte Antwort, statt das Modell neu auszuwerten, Werte neu zu runden oder System-One-Felder für replayed, billing oder request_id zum Body hinzuzufügen. Vom Modell gelieferte Felder mit diesen Namen sind keine System-One-Abrechnung. Vergleichen Sie nicht zwei unabhängige Auswertungen, um die Replay-Treue zu testen: eine neue Operation kann eine andere Antwort erzeugen.

Replay-Versuche zählen weiterhin zum Entscheidungs-Rate-Limit des Kontos. Der neue Versuch trägt die aktuellen Rate-Limit-Header des Kontos, daher ist nicht jeder HTTP-Header identisch mit dem ursprünglichen. Antworten verwenden Cache-Control: no-store; gewöhnliches Browser- oder Proxy-Caching ist nicht der Idempotenzmechanismus.

Das 24-Stunden-Fenster

Abgeschlossene Operationen können mit ihren Schlüsseln 24 Stunden ab Erstellung der Anfrage wiederhergestellt werden. Nach diesem Fenster kann derselbe Schlüssel eine neue abrechnungspflichtige Operation starten; er muss keinen Fehler für einen abgelaufenen Schlüssel liefern. Das ist kein dauerhafter Doppelschutz.

Ohne Operationsschlüssel ist das Wiederholen einer Anfrage eine separate Auswertung. Speichern Sie wichtige Antworten in Ihrer eigenen Anwendung, statt sich auf den Replay als dauerhaften Zugriff auf Ergebnisse zu verlassen.

Eine gewöhnliche fehlgeschlagene Auswertung gibt ihre reservierten Credits vor der Fehlerantwort zurück. Eine Unterbrechung kann eine Operation hängen lassen; Anfragen, die länger als 15 Minuten pending sind, werden für die Reconciliation infrage, aber das ist keine sofortige Fertigstellungs- oder Erstattungsfrist. Bewahren Sie den ursprünglichen Schlüssel und die Request-ID auf, bis der Ausgang bekannt ist. Eine nicht abgerechnete pending Operation ist keine Erlaubnis, nach 24 Stunden einen Ersatz zu erstellen: das Aufbewahrungsfenster ist keine Zusage, eine laufende Operation zu räumen.

Liefert eine Anfrage 503 request_reconciliation_pending, ist ihre Abbuchung noch nicht abgerechnet. X-System-One-Credits fehlt dann; fehlen bedeutet nicht null. Die Wiederherstellung ist möglicherweise nicht sofort möglich. Bewahren Sie den ursprünglichen Schlüssel und X-Request-Id, prüfen Sie die Nutzung in der Konsole und kontaktieren Sie support@system-one.dev, wenn der Ausgang unklar bleibt. Wechseln Sie nicht einfach zu einem neuen Schlüssel, um an dem Fehler vorbeizukommen.

SDK-Retry-Einstellungen

Das SDK-Beispiel deaktiviert automatische Retries mit maxRetries: 0, damit die Anwendung der Ergebnistabelle folgen kann. Die Retry-Richtlinie des SDK kann Netzwerkfehler und ausgewählte HTTP-Fehler erneut versuchen, aber sie löst die verschiedenen 409-Zustände nicht automatisch auf. Das Aktivieren von Retries erfordert weiterhin denselben gespeicherten Schlüssel und Body; das Deaktivieren von Retries bricht keine Server-Operation ab, deren Antwort verloren ging. Der Dienst wiederholt keine Modellauswertung automatisch.

Das Core-APIError liefert statusCode, requestId und retryAfterMs, aber nicht den vollständigen Body oder die Klassifizierungs-Header. Nutzen Sie Fetch, um X-System-One-Error-Code zu lesen, wenn Sie Konflikt, pending und fehlgeschlagen unterscheiden müssen. Befolgen Sie Retry-After, das Sekunden oder ein HTTP-Datum enthalten kann. Prüfen Sie X-System-One-Error-Source: ein 401 eines Modelldienstes bedeutet nicht, dass Ihre System-One-Anmeldung abgelaufen ist. Siehe die Fehlerreferenz.

Der getrennt gepflegte offizielle TypeSafe-Client hat eigene Retry-Einstellungen und benötigt ebenfalls einen ausdrücklich aufbewahrten Idempotenzschlüssel, wenn er diesen Dienst aufruft. Die Direktanbieter-Adapter des eigenständigen SDK folgen ihren eigenen Dienstverträgen; leiten Sie keine gehosteten Credit- oder Replay-Semantiken aus einer SDK-Paketversion ab.