Status 

Idempotency-key-ondersteuning is vandaag gedeeltelijk. Geselecteerde interne retry-mutaties — bijvoorbeeld order-billing retry en refund-billing retry — accepteren al een idempotency key en gebruiken die om downstream payment-processor-aanroepen te dedupliceren. Er is nog geen gestandaardiseerd idempotencyKey-argument voor alle customer-facing create-mutaties op de Zonos Graph; dat staat op de roadmap. Tot het beschikbaar is, gebruikt u de patronen hieronder om mutaties veilig opnieuw te proberen.

Standaard veilige mutaties 

Sommige mutaties zijn van nature idempotent omdat ze upserten op een stabiele identifier die u opgeeft. Bij dezelfde input is het resultaat hetzelfde — er is geen risico op duplicaten.

• Mutaties met een unieke merchant-supplied identifier (bijvoorbeeld een order-externalId) geven bij een herhaalde aanroep het bestaande record terug in plaats van een nieuw aan te maken.
• Read-only operaties (queries) zijn altijd veilig om opnieuw te proberen.

Wanneer u een eigen stabiele identifier aan de resource kunt koppelen die u aanmaakt, geeft u daaraan de voorkeur.

Patronen voor mutaties die niet van nature idempotent zijn 

Behandel mutaties die resources aanmaken zonder merchant-supplied key als at-most-once vanuit uw systeem:

1. Persisteer het verzoek vóór verzending. Schrijf een rij naar uw eigen database (status pending) vóór de netwerkaanroep.
2. Verstuur de mutatie. Bij succes registreert u het geretourneerde resource-id bij uw pending-rij (status committed).
3. Bij netwerkfout niet blind opnieuw proberen. Query de Zonos Graph om te bepalen of de resource is aangemaakt (bijvoorbeeld door resources te listen die in de afgelopen minuten voor uw account zijn aangemaakt, of door een gerelateerde resource te queryen die u kunt correleren). Probeer alleen opnieuw als u kunt bevestigen dat de resource niet aanwezig is.
4. Gebruik een unique constraint in uw eigen database op welke business key het verzoek ook vertegenwoordigt, zodat een dubbele retry vanuit uw applicatie geen dubbele submit kan doen.

Webhook-levering is at-least-once 

Ontwerp handlers voor Zonos-webhooks idempotent — hetzelfde event kan meer dan eens worden geleverd. Dedupliceer op event-id. Zie Webhooks voor het event-id-veld.

Waar het platform naartoe gaat 

Het onderliggende platform draait al idempotency-key-flows in productie voor billing retries: de key scopt een retry-poging en voorkomt dubbele payment-processor-aanroepen. We werken eraan hetzelfde patroon bloot te stellen als optioneel idempotencyKey-argument op customer-facing create-mutaties. Bij gebruik retourneert de Graph het oorspronkelijke antwoord voor elke volgende aanroep met dezelfde key binnen een retentieperiode. Deze pagina wordt bijgewerkt wanneer de surface algemeen beschikbaar is.

Als gestandaardiseerde idempotency keys op customer-facing mutaties uw integratie blokkeren, neem contact op met support.