LinkedIn Idempotency-Key: Uncertain Duplicate‑Write Prevention Across Mutating Endpoints

Short Answer

LinkedIn does not publish a definitive list of endpoints that honor X-Restli-Idempotency-Key with exactly-once semantics. The header is documented as optional and endpoint support is inconsistent. GraphQL mutations do not accept this header at all. If you need reliable duplicate-write prevention today, you must verify behavior per endpoint or implement your own idempotency layer.

What the Documentation Confirms

• The header exists for REST v1/v2 APIs and is accepted by some mutating endpoints (POST, PUT, PATCH).
• No public specification defines which endpoints guarantee exactly-once semantics.
• No documented expiration window or rate-limit for key reuse exists.
• GraphQL mutations are explicitly excluded from this mechanism.

Observed Behavior (Unverified, Varies by Endpoint)

Scenario	Possible Server Response
Same key, identical payload (retry)	Returns stored original response (ideal), or processes again (duplicate write), or rejects with 4xx
Same key, modified payload	May reject with 409/400, may silently ignore new payload, may create duplicate with new data
Key reused after long delay	May expire silently (new write), may reject as stale, may still return cached response

Practical Verification Steps

1. Pick one target endpoint (e.g., POST /ugcPosts or POST /shares).
2. Send a mutating request with a generated UUID as X-Restli-Idempotency-Key. Record the response body and HTTP status.
3. Immediately retry with the same key and identical payload. Compare response: identical body/status suggests idempotent replay; a new resource ID suggests duplicate write.
4. Retry with the same key but a changed payload (e.g., different text). Observe whether the server rejects, ignores changes, or creates a new record.
5. Wait 1 hour, then 24 hours, then retry with the original key and payload. Note when behavior changes.

Recommendation

Treat X-Restli-Idempotency-Key as a best-effort hint, not a contract. For any write that must not duplicate (billing, invitations, posts), implement application-level idempotency: generate a client-side key, store it with the request intent, and check before sending. Only rely on the header after you have verified the specific endpoint's behavior in a staging environment.

One Diagnostic Detail Needed

Which specific REST endpoint(s) are you targeting? Behavior differs between /ugcPosts, /shares, /organizationAcls, and others. Knowing the exact endpoint lets me confirm whether any public changelog or community report covers its idempotency support.