Recovery and retries

Retries are based on durable IDs and persisted idempotency keys, never on keeping one request alive.

Persist before sending

For each create or edit:

1. Persist the exact validated request body.
2. Persist a newly generated canonical lowercase UUID v4.
3. Submit both to Smore.
4. Persist the returned operation ID before replying to your caller.

After a transport failure, replay the identical body and key. Within 24 hours, Smore returns the same operation ID without starting work twice.

Retry table

Situation	Action
Mutation transport failure, immediate 429, or immediate 503	Replay the identical body and key, at most three automatic retries
Operation is processing	Schedule one later status read using Retry-After
Poll transport failure, 429, or 503	Retry at most three times with full jitter bounded by 1, 2, then 4 seconds and never before Retry-After
scene_operation_in_progress	Read current scene state and require explicit user retry
Terminal generation failure	Require explicit retry with a new key; edits use the current version
idempotency_expired	Recover create by exact externalRef; edits require a current-version user decision
Other nonretryable error	Do not repeat automatically

The transient retry counter survives short serverless invocations and resets after a successful HTTP response. Normal processing polls do not consume it.

Embed bootstrap recovery

Register the message listener before setting the iframe URL. Expect smore:ready or a valid smore:error within 15 seconds.

If neither arrives, ask your backend to revoke the old session and mint a new URL. Keep the existing iframe for a valid transient rate_limited response because Smore retries that same session.

Package delivery is at least once

The iframe may emit the same package ID more than once. Deduplicate notification jobs by expected scene ID plus package ID, then deduplicate downstream processing by package ID after validating the scene binding.