Support Idempotency-Key for writes that aren't naturally idempotent #129168

Follow-up to #128927. That work lets the schema mark writes that are naturally safe to resend (x-sentry-idempotent, #128930, #128999), and clients like the Sentry CLI now retry them on timeouts and 5xx. Writes that create something new on every call still can't be retried safely, because a timeout leaves the client unsure whether the first attempt was applied.

Examples

• ProjectPreprodArtifactAssembleEndpoint: a resend after the artifact leaves UPLOADING creates a second artifact and enqueues another assemble task. The CLI keeps a hand-written retry opt-in for its poll loop.
• createOrganizationReleaseDeploy: every call creates a new Deploy.
• Plain creates such as createOrganizationProject, createOrganizationTeam, createOrganizationDashboard, and createOrganizationMonitor.

Proposal

Accept an Idempotency-Key request header on opted-in non-safe operations, following draft-ietf-httpapi-idempotency-key-header:

1. Store the key, scoped to the caller (org + token or user) and operation, with a fingerprint of the request and the final response, for a bounded TTL.
2. A repeat with the same key and fingerprint replays the stored response without running the handler.
3. The same key with a different payload returns 422. A repeat while the first request is still running returns 409.
4. Let endpoints opt in the same way as idempotent_methods, and publish that in the schema (for example x-sentry-idempotency-key: true). Generated clients (@sentry/api, CLI, MCP) can then send a key per logical operation and retry those writes too.

Open questions

• Storage and TTL: Redis is enough for retry windows, but is a short TTL acceptable for long-running uploads?
• Which responses get stored: only 2xx, or deterministic 4xx too? 5xx should never be stored.
• Scope: are cell-silo endpoints enough at first, or does this need to work through the control silo proxy too?
• Opt-in per endpoint, or a default for all published POST operations?

via BYK.

--

View Junior Session [Sentry]