From 655dc620e3176da7f19cb0ee2b3029a9012bb115 Mon Sep 17 00:00:00 2001 From: John Spaetzel Date: Wed, 18 Nov 2026 13:10:24 -0800 Subject: [PATCH] Document Idempotency-Key reuse on 409 conflict errors. Callers need to know a reused key or an in-progress POST or PUT can return 409, and how to retry with the same key. Co-authored-by: Cursor --- openapi-fern.yaml | 4 ++-- openapi-sdk.yaml | 4 ++-- openapi.yaml | 4 ++-- translations/en.yaml | 4 ++-- 4 files changed, 8 insertions(+), 8 deletions(-) diff --git a/openapi-fern.yaml b/openapi-fern.yaml index 24dbe878a..619195f96 100644 --- a/openapi-fern.yaml +++ b/openapi-fern.yaml @@ -38226,8 +38226,8 @@ x-error-codes: conflict: http_status: 409 summary: The request was well-formed but conflicts with the current state. - cause: The target resource is in a state incompatible with the request (e.g. a signature request is still being set up). - remediation: 'Wait briefly and retry, or listen for a callback event confirming the resource is ready.' + cause: The target resource is in a state incompatible with the request (e.g. a signature request is still being set up). A POST or PUT can also return this status when an Idempotency-Key header is reused with different parameters, or while the original request is still in progress. + remediation: 'Wait briefly and retry, or listen for a callback event confirming the resource is ready. To make a POST or PUT safe to retry, send the same Idempotency-Key header (1 to 255 characters) with the other headers for that request. The same key and request within 24 hours returns the original response, with Idempotent-Replayed: true. Use a new key for a different request.' retryable: conditional exceeded_rate: http_status: 429 diff --git a/openapi-sdk.yaml b/openapi-sdk.yaml index b59759d5e..e5f802dc0 100644 --- a/openapi-sdk.yaml +++ b/openapi-sdk.yaml @@ -15934,8 +15934,8 @@ x-error-codes: conflict: http_status: 409 summary: 'The request was well-formed but conflicts with the current state.' - cause: 'The target resource is in a state incompatible with the request (e.g. a signature request is still being set up).' - remediation: 'Wait briefly and retry, or listen for a callback event confirming the resource is ready.' + cause: 'The target resource is in a state incompatible with the request (e.g. a signature request is still being set up). A POST or PUT can also return this status when an Idempotency-Key header is reused with different parameters, or while the original request is still in progress.' + remediation: 'Wait briefly and retry, or listen for a callback event confirming the resource is ready. To make a POST or PUT safe to retry, send the same Idempotency-Key header (1 to 255 characters) with the other headers for that request. The same key and request within 24 hours returns the original response, with Idempotent-Replayed: true. Use a new key for a different request.' retryable: conditional exceeded_rate: http_status: 429 diff --git a/openapi.yaml b/openapi.yaml index 56e8f68f9..25f699870 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -17787,8 +17787,8 @@ x-error-codes: conflict: http_status: 409 summary: 'The request was well-formed but conflicts with the current state.' - cause: 'The target resource is in a state incompatible with the request (e.g. a signature request is still being set up).' - remediation: 'Wait briefly and retry, or listen for a callback event confirming the resource is ready.' + cause: 'The target resource is in a state incompatible with the request (e.g. a signature request is still being set up). A POST or PUT can also return this status when an Idempotency-Key header is reused with different parameters, or while the original request is still in progress.' + remediation: 'Wait briefly and retry, or listen for a callback event confirming the resource is ready. To make a POST or PUT safe to retry, send the same Idempotency-Key header (1 to 255 characters) with the other headers for that request. The same key and request within 24 hours returns the original response, with Idempotent-Replayed: true. Use a new key for a different request.' retryable: conditional exceeded_rate: http_status: 429 diff --git a/translations/en.yaml b/translations/en.yaml index 62a6745b9..f896f058f 100644 --- a/translations/en.yaml +++ b/translations/en.yaml @@ -2229,8 +2229,8 @@ "ErrorCatalog::not_found::REMEDIATION": "Verify the id and that the resource belongs to the authenticated account." "ErrorCatalog::conflict::SUMMARY": "The request was well-formed but conflicts with the current state." -"ErrorCatalog::conflict::CAUSE": "The target resource is in a state incompatible with the request (e.g. a signature request is still being set up)." -"ErrorCatalog::conflict::REMEDIATION": "Wait briefly and retry, or listen for a callback event confirming the resource is ready." +"ErrorCatalog::conflict::CAUSE": "The target resource is in a state incompatible with the request (e.g. a signature request is still being set up). A POST or PUT can also return this status when an Idempotency-Key header is reused with different parameters, or while the original request is still in progress." +"ErrorCatalog::conflict::REMEDIATION": "Wait briefly and retry, or listen for a callback event confirming the resource is ready. To make a POST or PUT safe to retry, send the same Idempotency-Key header (1 to 255 characters) with the other headers for that request. The same key and request within 24 hours returns the original response, with Idempotent-Replayed: true. Use a new key for a different request." "ErrorCatalog::exceeded_rate::SUMMARY": "Your account's API request rate limit has been exceeded." "ErrorCatalog::exceeded_rate::CAUSE": "Too many requests were sent within the rate-limit window for this request type."