Document Idempotency-Key reuse on 409 conflict errors

openapi-fern.yaml

@@ -3091,9 +3091,6 @@ paths:
       requestBody:
         required: true
         content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/DocumentFieldDetectionRequest'
           multipart/form-data:
             schema:
               $ref: '#/components/schemas/DocumentFieldDetectionRequest'
@@ -23533,6 +23530,11 @@ components:
           pattern: ^(?:all|\d+(?:-\d+)?(?:,\d+(?:-\d+)?)*)$
           example: '0-2,5,7-9'
       type: object
+      oneOf:
+        - required:
+            - file
+        - required:
+            - file_url
     EmbeddedEditUrlRequest:
       properties:
         allow_edit_ccs:
@@ -30201,6 +30203,16 @@ components:
             default: Hello API Event Received
       x-fern-audiences:
         - events
+  parameters:
+    IdempotencyKey:
+      name: Idempotency-Key
+      in: header
+      description: Optional header on an authenticated POST or PUT. Reuse the same key when retrying the same request. See [Idempotency](/api/manual-reference-pages/idempotency) for details.
+      required: false
+      schema:
+        type: string
+        maxLength: 255
+        minLength: 1
   examples:
     AccountCreateRequest:
       summary: Default Example
@@ -35116,6 +35128,11 @@ components:
         type: integer
         format: int64
         example: 1430170900
+    Idempotent-Replayed:
+      description: Sent when the request included an Idempotency-Key. True when replaying a stored response, false otherwise. See [Idempotency](/api/manual-reference-pages/idempotency) for details.
+      required: false
+      schema:
+        type: boolean
   securitySchemes:
     api_key:
       type: http
@@ -35349,8 +35366,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

openapi-raw.yaml

@@ -1198,9 +1198,6 @@ paths:
       requestBody:
         required: true
         content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/DocumentFieldDetectionRequest'
           multipart/form-data:
             schema:
               $ref: '#/components/schemas/DocumentFieldDetectionRequest'
@@ -8119,6 +8116,13 @@ components:
           pattern: '^(?:all|\d+(?:-\d+)?(?:,\d+(?:-\d+)?)*)$'
           example: '0-2,5,7-9'
       type: object
+      oneOf:
+        -
+          required:
+            - file
+        -
+          required:
+            - file_url
     EmbeddedEditUrlRequest:
       properties:
         allow_edit_ccs:
@@ -14234,6 +14238,17 @@ components:
             default: 'Hello API Event Received'
       x-fern-audiences:
         - events
+  parameters:
+    IdempotencyKey:
+      name: Idempotency-Key
+      in: header
+      description: '_t__Common::Idempotency::KEY'
+      required: false
+      schema:
+        type: string
+        maxLength: 255
+        minLength: 1
+      x-hideOn: sdk
   examples:
     AccountCreateRequest:
       summary: 'Default Example'
@@ -14992,6 +15007,12 @@ components:
         type: integer
         format: int64
         example: 1430170900
+    Idempotent-Replayed:
+      description: '_t__Common::Idempotency::REPLAYED'
+      required: false
+      schema:
+        type: boolean
+      x-hideOn: sdk
   securitySchemes:
     api_key:
       type: http

openapi-sdk.yaml

@@ -1163,9 +1163,6 @@ paths:
       requestBody:
         required: true
         content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/DocumentFieldDetectionRequest'
           multipart/form-data:
             schema:
               $ref: '#/components/schemas/DocumentFieldDetectionRequest'
@@ -8061,6 +8058,13 @@ components:
           pattern: '^(?:all|\d+(?:-\d+)?(?:,\d+(?:-\d+)?)*)$'
           example: '0-2,5,7-9'
       type: object
+      oneOf:
+        -
+          required:
+            - file
+        -
+          required:
+            - file_url
     EmbeddedEditUrlRequest:
       properties:
         allow_edit_ccs:
@@ -14940,8 +14944,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

openapi.yaml

@@ -1163,9 +1163,6 @@ paths:
       requestBody:
         required: true
         content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/DocumentFieldDetectionRequest'
           multipart/form-data:
             schema:
               $ref: '#/components/schemas/DocumentFieldDetectionRequest'
@@ -8061,6 +8058,13 @@ components:
           pattern: '^(?:all|\d+(?:-\d+)?(?:,\d+(?:-\d+)?)*)$'
           example: '0-2,5,7-9'
       type: object
+      oneOf:
+        -
+          required:
+            - file
+        -
+          required:
+            - file_url
     EmbeddedEditUrlRequest:
       properties:
         allow_edit_ccs:
@@ -14771,6 +14775,16 @@ components:
             default: 'Hello API Event Received'
       x-fern-audiences:
         - events
+  parameters:
+    IdempotencyKey:
+      name: Idempotency-Key
+      in: header
+      description: 'Optional header on an authenticated POST or PUT. Reuse the same key when retrying the same request. See [Idempotency](/api/manual-reference-pages/idempotency) for details.'
+      required: false
+      schema:
+        type: string
+        maxLength: 255
+        minLength: 1
   examples:
     AccountCreateRequest:
       summary: 'Default Example'
@@ -15526,6 +15540,11 @@ components:
         type: integer
         format: int64
         example: 1430170900
+    Idempotent-Replayed:
+      description: 'Sent when the request included an Idempotency-Key. True when replaying a stored response, false otherwise. See [Idempotency](/api/manual-reference-pages/idempotency) for details.'
+      required: false
+      schema:
+        type: boolean
   securitySchemes:
     api_key:
       type: http
@@ -15811,8 +15830,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

translations/en.yaml

@@ -1387,6 +1387,8 @@
 "Common::RateLimiting::LIMIT": The maximum number of requests per hour that you can make.
 "Common::RateLimiting::REMAINING": The number of requests remaining in the current rate limit window.
 "Common::RateLimiting::RESET": The Unix time at which the rate limit will reset to its maximum.
+"Common::Idempotency::KEY": Optional header on an authenticated POST or PUT. Reuse the same key when retrying the same request. See [Idempotency](/api/manual-reference-pages/idempotency) for details.
+"Common::Idempotency::REPLAYED": Sent when the request included an Idempotency-Key. True when replaying a stored response, false otherwise. See [Idempotency](/api/manual-reference-pages/idempotency) for details.
 
 "EmbeddedEditUrlResponseExample::SUMMARY": Embedded Edit URL
 "EmbeddedSignUrlResponseExample::SUMMARY": Embedded Sign URL
@@ -2070,8 +2072,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."