After batch APIs (3 Oct), this post is a dedicated treatment of idempotency keys: client minting, scope, result stores, TTL, concurrency, write-only use, upstream provider keys and links to retry/outbox.

इदमर्थकुञ्चिका: A Metrical Codification of Idempotency Keys (with English glosses)

What this post is about

An idempotency key is a client-generated token that makes multiple HTTP attempts of the same intent produce one business effect.

Topics covered

1. Retries and double-submit
2. Client-generated stable keys
3. Tenant + operation scope
4. Storing and replaying results
5. TTL on key records
6. Concurrent first attempts
7. Writes vs safe GETs
8. Failed vs succeeded first try
9. Upstream provider keys
10. Links to retry and outbox

Sanskrit title

इदमर्थकुञ्चिका = idamartha-kuñcikā “key of same-meaning/same-effect” (idempotency key).

English

All English is in minimizable details. Sanskrit is the default open layer.

ग्राह्यम् / Keep

१. ग्राहकजन्मः: client creates key before first try
२. स्थिरपुनर्योगः: same key on every retry
३. क्षेत्रभेदः: tenant and op family in scope
४. फलसंचयः: persist first success response
५. कालसीमा: TTL and storage bound
६. संघर्षनीतिः: unique constraint or lock on begin
७. प्रदातृवाहः: forward key to payment/SMS APIs

त्याज्यम् / Avoid

• server-new key each attempt
• one global key space for all op types
• replay success body after partial side effect without care

पदच्छेदः
जाले यत्नः यदि द्विः पतति तदा कर्म द्विः मा भूत् । इदमर्थकुञ्चिका तस्माद् एकफलसेतुः ॥१॥

Word-for-word

Gloss table

English sense
Retries, double-clicks and client timeouts make the same logical intent hit the server more than once. An idempotency key makes those hits share one business outcome.

Context / topic
Topic: why idempotency keys exist. Links to retry treatise.

वृत्तमिति: ८-८-८-८।

पदच्छेदः
कुञ्चिका ग्राहकेन पूर्वं दीयते स्थिरा च । सर्वरे जननं पश्चात् विफले ॥२॥

Word-for-word

Gloss table

English sense
The client must generate the key before the first attempt and reuse it on every retry. If the server creates a new key per try, duplicates cannot be detected.

Context / topic
Topic: client-owned stable keys.

वृत्तमिति: ८-८-८-८।

पदच्छेदः
क्षेत्रं कुटुम्बः कर्मजातिः कुञ्चिका च त्रयम् । सङ्कीर्णे द्विःदाने भयम् ॥३॥

Word-for-word

Gloss table

English sense
Scope keys as tenant + operation type + unique intent id so two different payments never share storage.

Context / topic
Topic: key scope. Links to multi-tenancy.

वृत्तमिति: ८-८-८-८।

पदच्छेदः
फलाभिलिखनं प्रथमसिद्धे रक्ष्यम् । द्वितीये तदेव उत्तरम् ॥४॥

Word-for-word

Gloss table

English sense
On first success store the response (or resource id). Later requests with the same key return that record without re-executing side effects.

Context / topic
Topic: response replay store.

वृत्तमिति: ८-८-८-८।

पदच्छेदः
कालसीमा कुञ्चिकायाः मिता स्यात् न तु अनन्ता स्मृतिः । अतिजीर्णे नवीनं जन्म ॥५॥

Word-for-word

Gloss table

English sense
Idempotency records need TTL and storage bounds. Document whether an expired key starts a new intent or rejects.

Context / topic
Topic: retention of idempotency records.

वृत्तमिति: एकादशाक्षराः पादाः।

पदच्छेदः
समकाले द्वौ यदि एककुञ्चिकया तदा एकः जेता । अपरः प्रतीक्षेत वा तुल्यफलम् ॥६॥

Word-for-word

Gloss table

English sense
Concurrent first attempts need a lock or unique constraint so only one side effect runs; the other waits or reads the winner result.

Context / topic
Topic: concurrent begin. Links to distributed lock.

वृत्तमिति: ८-८-८-८।

पदच्छेदः
GET इदमर्थः स्वभावतः लेखे तु कुञ्चिका । सर्वकर्मसु एकन्यायो मूढः ॥७॥

Word-for-word

Gloss table

English sense
Do not require keys on pure reads. Focus on POST/PATCH that create charges, sends or irreversible state.

Context / topic
Topic: when keys are required.

वृत्तमिति: ८-८-८-८।

पदच्छेदः
त्रुटौ प्रथमं यदि असिद्धं तदा कुञ्चिका जीवतु । सिद्धिलेखं विना पुनर्लेखः ॥८॥

Word-for-word

Gloss table

English sense
If the first attempt fails before any side effect, a retry with the same key should be allowed to execute. If success was stored, never redo.

Context / topic
Topic: failed vs succeeded first attempt.

वृत्तमिति: ८-८-८-८।

पदच्छेदः
प्रदातृकुञ्चिका बाह्ये अपि वहेत् । द्विः शुल्कं मा भूत् पथि ॥९॥

Word-for-word

Gloss table

English sense
When calling payment or SMS providers, forward or derive a stable provider idempotency key so your retry does not double-charge upstream.

Context / topic
Topic: upstream keys. Links to email/SMS and vendor risk.

वृत्तमिति: ८-८-८-८।

पदच्छेदः
पुनःप्रयासन्यायः कुञ्चिकां याचते बहिर्पटलं जन्म रक्षति । उभौ मिलित्वा द्विः कर्म नश्यति ॥१०॥

Word-for-word

Gloss table

English sense
Retries need keys; outboxes need stable event ids. Together they stop duplicate business effects across HTTP and async paths.

Context / topic
Topic: series links to retry and outbox.

सन्धिः: यत्नः द्वारं; कुञ्चिका फलम्; पटलः जन्म।

वृत्तमिति: एकादशाक्षराः पादाः।

पदच्छेदः
ग्राहकजन्मः क्षेत्रं फललेखः कालः संघर्षः पञ्चकम् । एभिरिदमर्थकुञ्चिका एकफलसमन्विता ॥११॥

Word-for-word

Gloss table

English sense
Five limbs: client-minted stable keys, scoped storage, result replay, TTL and safe concurrent first-writers.

Context / topic
Topic: checklist.

वृत्तमिति: ८-८-८-८।

पदच्छेदः
इतीदमर्थकुञ्चिकासार एकफलसमन्वितः । मितं फलं क्रियायोग्यं तन्त्रधर्मः स उच्यते ॥१२॥

Word-for-word

Gloss table

English sense
Closing: one user intent, one business fruit, even when the network stutters.

Context / topic
Topic: close.

उपसंहारन्यायः: पूर्वं कुञ्चिकां देहि; सिद्धे फलं रक्ष; द्विः मा कुरु।

वृत्तमिति: ८-८-८-८।

१. Why keys
२. Client mint
३. Scope
४. Result store
५. TTL
६. Concurrency
७. Writes only
८. Fail vs success
९. Upstream
१०. Retry/outbox link
११. Five limbs
१२. Close

1. Prior: retry 2026-08-14; outbox 2026-09-28; batch API 2026-10-03; notifications 2026-09-24.
2. Domain: HTTP idempotency keys for side-effecting APIs.
3. English is minimizable; Sanskrit-first default.
4. Style: no em dash; no Oxford comma in English clauses.