SDK

Nieuwe pogingen en idempotentie

Wat opnieuw geprobeerd wordt, wat bewust niet, en waarom een opnieuw geprobeerde verzending niet kan dupliceren.

Verzendingen

De client hangt aan elke verzending (emails.send, emails.sendBatch en templates.send) een Idempotency-Key, één keer gegenereerd per **aanroep** en hergebruikt door de retries van die aanroep. De API claimt die sleutel voordat ze iets verstuurt, dus een retry speelt het oorspronkelijke bericht opnieuw af in plaats van een tweede te versturen, terwijl twee bewuste send()-aanroepen nog steeds twee keer versturen. Dat zijn verschillende intenties en die blijven verschillend.

Geef je eigen idempotencyKey mee om die garantie over processen heen uit te strekken, zodat een job die gecrasht is en opnieuw draait zijn verzendingen opnieuw afspeelt in plaats van ze te herhalen.

idempotency.ts

await openemail.emails.send(message, { idempotencyKey: `invoice:${invoice.id}` })

Leid hem af van datgene wat de verzending nodig maakte. Nooit van een klok. Een sleutel hergebruiken met een andere body wordt geweigerd met idempotency_key_reuse in plaats van stilzwijgend opnieuw afgespeeld.

Al het overige

Elke leesactie wordt opnieuw geprobeerd. Een schrijfactie alleen daar waar een tweede identiek request niets anders kan betekenen dan het eerste, en een verzending valt daaronder omdat haar idempotency key van een herhaling een replay maakt.

Aanroep	Opnieuw geprobeerd	Waarom
Elke leesactie	Ja	Er verandert niets.
`emails.send`, `emails.sendBatch`, `templates.send`	Ja	Een idempotency key maakt van een herhaling een replay.
`emails.cancel`, `emails.reschedule`	Ja	Puur het zetten van een benoemde status.
`threads.update`, `threads.trash`	Ja	Het zetten van labels. Twee keer toepassen is hetzelfde als één keer toepassen.
`threads.snooze`, `threads.unsnooze`	Ja	Het wektijdstip staat in de body en wordt niet afgeleid uit het tijdstip van binnenkomst.
`labels.update`, `webhooks.update`, `settings.update`, `roles.update`, `members.update`	Ja	Puur het zetten van benoemde velden.
`members.grantAddress`, `rules.reorder`	Ja	De toekenning is een upsert, en de volgorde wordt volledig opgegeven.
`templates.publish`	Ja	Een head publiceren die al gepubliceerd is, geeft die ongewijzigd terug.
`templates.preview`, `rules.test`	Ja	Ze renderen of evalueren en schrijven niets weg.
`drafts.create`, `labels.create`, `webhooks.create`, `templates.create`, `rules.create`, `roles.create`, `tempMail.create`	Nee	Een nieuwe poging laat twee objecten achter.
`drafts.update`	Nee	Lees het id af van het resultaat van elke schrijfactie in plaats van het id te hergebruiken dat je verstuurd hebt.
`drafts.delete`, `labels.delete`, `webhooks.delete`, `templates.delete`, `rules.delete`, `roles.delete`, `members.remove`, `members.revokeAddress`, `tempMail.delete`, `tempMail.deleteMessage`	Nee	Een retry na een verloren response meldt een mislukking voor werk dat gelukt is.
`webhooks.rotateSecret`	Nee	Een tweede rotatie maakt het secret ongeldig dat de eerste poging teruggaf.
`webhooks.test`	Nee	Het zou een tweede synthetische bezorging versturen.
`emails.translate`	Nee	Het verbruikt model-aanroepen, dus een nieuwe poging na een onbeantwoord verzoek koopt hetzelfde antwoord twee keer.
Elke andere schrijfactie	Nee	Wordt één keer verstuurd, en een fout wordt gemeld in plaats van herhaald.

De backoff

Begrensd door maxRetries op de client, standaard twee extra pogingen.
Alleen na een netwerkfout of een 408, 500, 502, 503 of 504. Een 429 wordt alleen opnieuw geprobeerd wanneer die een Retry-After meestuurt, en deze API stuurt die niet mee, dus een rate limit gooit meteen een fout. Elke andere status gooit onmiddellijk.
Exponentieel van een halve seconde tot acht, met jitter, zodat een vloot clients niet opnieuw synchroniseert op het moment van herstel.
Gestuurd door Retry-After in beide vormen, delay-seconds en HTTP-date. Wanneer de server een wachttijd noemt, wacht de client precies zo lang in plaats van terug te schalen.
Een server die om meer dan een minuut vraagt, wordt gelezen als een opdracht aan de client om te stoppen in plaats van te wachten, dus de fout wordt opgeworpen met retryAfterSeconds erop. Eerder terugkomen dan gevraagd is die wachttijd niet respecteren.
Een AbortSignal van de aanroeper wordt nooit opnieuw geprobeerd. Afbreken gooit onmiddellijk een OpenEmailNetworkError, vanuit het verzoek of vanuit de wachttijd vóór de volgende poging.