# Deduplication and retries

Give each logical event a stable source-scoped key so a network retry cannot create a second inbox item while the original is retained.

## Build a stable key

Derive deduplicationKey from immutable event identity, not the retry attempt or current time. Useful shapes include deploy:<service>:<commit>, run:<workflow>:<run-id>, and invoice:<invoice-id>:paid. The same string may be reused by another source because uniqueness is scoped to the source selected by the API key.

## What a duplicate means

- The first accepted request returns 201 and created: true.
- A repeat returns 200, created: false, and the original notification id.
- The service does not compare the repeated payload with the original payload.
- The guarantee lasts while the original notification exists; retention can eventually permit the key to create a new item.

> **Retry only with event identity.** After a timeout or lost response, automatically retry create only when a deduplicationKey was sent. Without one, the server may already have committed the first request.

## Verify the retry boundary

> **Primary contract evidence · verified Sep 3, 2026.** HTTP does not make POST idempotent by itself. FYInbox defines its source-scoped deduplication behavior in the public OpenAPI contract and request schema, including the retention boundary and ambiguous-retry rule.

- [FYInbox OpenAPI](/openapi.json)
- [Create request JSON Schema](/json-schema/create-notification.request.schema.json)
- [RFC 9110: Idempotent Methods](https://www.rfc-editor.org/rfc/rfc9110.html#name-idempotent-methods)