Idempotency and retries
How the Idempotency-Key header works on Flowyn creates, how Flowyn retries HTTP jobs and webhook deliveries, and how receivers should deduplicate.
How idempotency works on create requests
Send an Idempotency-Key header on creates such as POST /v1/events, /v1/jobs, /v1/schedules, /v1/monitors, document operations, and agent runs. If the same key arrives again with the same body within 24 hours, Flowyn returns the original response instead of creating a second resource. The same key with a different body returns 409 idempotency_mismatch.
Idempotency-Key: order-123-completedHow Flowyn retries durable HTTP jobs
A job attempt succeeds on a 2xx. Timeouts, connection errors, 408, 429, and 5xx responses are retried; other 4xx responses and blocked destinations fail without a retry. The wait doubles from about one second, varies by ±20%, and is capped at five minutes. A Retry-After from the destination is honoured. Jobs default to 5 attempts and accept up to 20.
How Flowyn retries webhook deliveries
A delivery gets up to 8 attempts. After a failed attempt Flowyn waits about 5 seconds, then 5 minutes, 30 minutes, 2 hours, 5 hours, 10 hours, and 10 hours, each varied by ±20%.
| Attempt | Wait before (approx.) |
|---|---|
| 1 | immediate |
| 2 | 5 s |
| 3 | 5 min |
| 4 | 30 min |
| 5 | 2 h |
| 6 | 5 h |
| 7 | 10 h |
| 8 | 10 h |
At-least-once, so deduplicate
A receiver may see the same request twice, for example when it processed a delivery but the response was lost. HTTP jobs send Idempotency-Key: <job id> on every attempt. Webhook deliveries send webhook-id: <event id>, which stays the same across retries. Store the id and ignore repeats.
What Flowyn does not retry
Errors in your own API requests are returned to you, not retried. Fix the request and send it again with the same idempotency key.