Skip to content

Document Idempotency-Key reuse on 409 conflict errors - #572

Draft
jspaetzel wants to merge 6 commits into
mainfrom
docs/idempotency-key-conflict
Draft

jspaetzel wants to merge 6 commits into
mainfrom
docs/idempotency-key-conflict

Conversation

@jspaetzel

@jspaetzel jspaetzel commented Oct 7, 2026 •

Copy link
Copy Markdown
Member

Summary

  • Document that a POST or PUT can return 409 when an Idempotency-Key header is reused with different parameters, or while the original request is still in progress.
  • Add an optional Idempotency-Key header and an Idempotent-Replayed response header to authenticated POST and PUT operations in the API reference.
  • Mark both with x-hideOn: sdk so OpenAPI Generator does not add an idempotency argument to every SDK method. Callers pass the header through the existing per-call headers or options argument.

Test plan

  • Confirm OpenApi::DESCRIPTION and the spec info.description remain Dropbox Sign v3 API.
  • Confirm ErrorCatalog::conflict::SUMMARY is unchanged and the conflict cause and remediation still describe key reuse.
  • Confirm openapi.yaml and openapi-fern.yaml list Idempotency-Key and Idempotent-Replayed on a POST, and a GET does not.
  • Confirm openapi-sdk.yaml and the SDK sources do not add an idempotency parameter to method signatures.

jspaetzel and others added 6 commits October 7, 2026 10:21
Callers need to know a reused key or in-progress POST/PUT can return 409, and how to retry with the same key.

Co-authored-by: Cursor <cursoragent@cursor.com>
Add the optional request header and Idempotent-Replayed response header to the spec, and regenerate the SDKs so each client can pass the key on a single call.

Co-authored-by: Cursor <cursoragent@cursor.com>
Leave the header in the API reference, and pass it through each SDK's existing headers or options argument instead of a dedicated parameter.

Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant