Prevent duplicate letters when an API request times out

The ambiguous timeout problem

Your server submits a customer letter, IRIS creates the order, and the network connection closes before your server receives the response. Your application cannot tell from that timeout alone whether an order exists. Retrying with a newly generated key treats the request as a new mailing and can produce a second letter.

The correct place to create the key is when you persist the approved mailing intent. Keep it alongside the exact payload. Do not generate it inside a generic HTTP retry loop. A restarted worker must recover the saved intent instead of reconstructing a new one from memory.

How IRIS handles the same key again

IRIS scopes idempotency to the developer account. Its current implementation hashes the validated mailing payload and compares it with the original request. Preserve the original payload and its serialization structure on retry.

• IRIS API documentation and current limits ↗
• IRIS OpenAPI contract ↗

Deduplicate the business event as well

An HTTP idempotency key does not decide whether two CRM events describe the same business action. If your CRM delivers the same event twice and your handler invents two intent IDs, the mailing API receives two distinct requests. Add a unique constraint in your application around the source event and document version.

For example, use a unique pair such as source_event_id and correspondence_type to locate a saved intent. Persist the document ID, approved payload, reviewer, key, and submission state in that row. Two workers should compete for the same row, not independently approve or submit duplicate intents. These are application design suggestions; IRIS does not expose a CRM-event deduplication endpoint.

Make recovery a small state machine

Keep the response-handling policy understandable to the next person on call. A retry should preserve a known intent, and a changed business request should receive fresh review.

1. Persist the approved payload and key before making the first POST /v1/mailings request.
2. On success, save orderId and the returned price. Treat replay: true as recovery of the existing order.
3. On a timeout or uncertain connection failure, mark submission uncertain and retry the saved request using bounded backoff.
4. On a validation or 409 response, stop automatic resubmission and reconcile the source record and error code.
5. When details must change, resolve the earlier intent before approving a new one. A new key is not a way to repair an unknown earlier outcome.

Test a lost response before mailing customers

In a local test, have your fake API create an order and then close the connection without returning the JSON response. Restart the worker and confirm it sends the same key and unchanged payload. The recovered result should attach to the original intent. This checks a meaningful failure mode without creating physical mail.

Also deliver the same source event twice, start two workers at once, and mutate the document after approval. Your system should produce one intent for the duplicate event and require renewed review for the changed document. Do not treat a missing tracking number as evidence that no order was created.