Retry a idempotence

Sítě selhávají – zvlášť na mobilu. Všechna Frontmail SDK neúspěšné požadavky automaticky opakují, a to bezpečně: opakované odeslání nikdy nevede k duplicitnímu e-mailu ani k dvojímu stržení kreditů.

Co se opakuje

Situace	Opakuje se?
Síťová chyba (offline, DNS, přerušené spojení)	✓
Timeout (`timeoutMs`, výchozí 15 s na pokus)	✓
Odpovědi `5xx`	✓
`429 rate_limited`	✓ – počká podle `Retry-After` (pokud je 60 s nebo méně)
Chyby `4xx` – validace, autentizace, origin, CAPTCHA	✗ – opakování by nepomohlo
Blokace na straně klienta (`blockHeadless`, `blockList`, `limitRate`)	✗

Výchozí politika: 3 retry po prvním pokusu, exponenciální backoff začínající na 300 ms s plným jitterem, mezi pokusy nejvýše 10 s. Nastavíte ji volbou retry:

init({ publicKey: 'pk_4f2a…', retry: { retries: 5, baseDelayMs: 500, maxDelayMs: 20_000 } });
init({ publicKey: 'pk_4f2a…', retry: false }); // vypnutí

Idempotency klíče

Každé logické volání send() dostane jako Idempotency-Key náhodné UUID a všechny retry tohoto odeslání používají stejný klíč. Frontmail si klíče na serveru pamatuje 24 hodin:

stejný klíč se stejným tělem vrátí původní odpověď (stejné message_id) a znovu nic neodešle,
stejný klíč s jiným tělem skončí chybou 409 idempotency_conflict.

Pokud tedy první pokus do Frontmailu ve skutečnosti dorazil, jen se ztratila odpověď, retry prostě dostane původní výsledek.

Vlastní klíče

Explicitní klíč předejte, když se může opakovat samotný spouštěč – webhook doručený dvakrát, job, který se restartuje, uživatel, který odešle formulář dvakrát ve dvou záložkách:

// @frontmail/node
await frontmail.send({ templateId: 'tpl_receipt', params, idempotencyKey: `receipt-${order.id}` });

// @frontmail/browser – volby jsou posledním argumentem
await send('svc_01J9…', 'tpl_receipt', params, { idempotencyKey: `receipt-${order.id}` });

Klíč může mít až 255 znaků. Pro každý samostatný e-mail použijte nový klíč – když stejný klíč použijete pro jiný e-mail, místo odeslání dostanete chybu.

S REST API posílejte hlavičku sami:

curl https://api.frontmail.dev/v1/send \
  -H 'Idempotency-Key: receipt-A-1042' \
  -H 'Authorization: Bearer sk_…' \
  -H 'Content-Type: application/json' \
  -d '{ "template_id": "tpl_receipt", "template_params": { "order_id": "A-1042" } }'

U hromadného odeslání nastavte idempotencyKey (v REST API idempotency_key) u každé zprávy zvlášť.

Když API zprávu přijalo

Jakmile API vrátí 202, o opakování doručení se stará Frontmail: odesílač opakuje přechodné chyby poskytovatele s backoffem, při chybách autentizace nebo trvalých chybách přepne na záložní službu a když je služba nefunkční, zprávy zadrží. Váš kód nemusí nic dělat – pokud potřebujete, výsledek zkontrolujte přes getStatus() nebo v Historii.