Skip to content
Dockt Dockt DOCKT

Idempotency

Send Idempotency-Key on supported create, upload, and invitation-resend requests. The key lets you safely retry when your client doesn’t know whether Dockt completed the first request.

Supported operations

Section titled “Supported operations”

Dockt applies idempotency to:

  • POST /v1/workspaces
  • POST /v1/account/invitations
  • POST /v1/account/invitations/{invitationId}/resend
  • POST /v1/account/api-credentials
  • POST /v1/api-credentials
  • POST /v1/assessments
  • POST /v1/documents
  • POST /v1/assessments/{assessmentId}/documents
  • POST /v1/webhooks

The OpenAPI operation includes the header when it is supported.

Choose a key

Section titled “Choose a key”

Use a stable key that represents one logical operation in your system:

Idempotency-Key: assessment-worker-case-1042-passport

Avoid personal data, filenames, bearer tokens, or other secrets in the key. A random value stored with your operation record also works.

Use the same key only when retrying the same method, route, and request body with the same credential or session principal. Use a new key for a different resource or changed request.

Replay behavior

Section titled “Replay behavior”

Keys are scoped to the authenticated principal, HTTP method, and route and retained for 24 hours.

  • The same key and equivalent request body replay the successful response.
  • The replay receives the request ID for the current retry.
  • Reusing a key with a different body returns 409 Conflict.
  • Reusing a key while the first request is still running returns 409 Conflict.

For JSON requests, semantically equivalent object key ordering is treated consistently. For multipart uploads, the file content and part metadata are part of the request identity.

Retry pattern

Section titled “Retry pattern”
  1. Create and persist the idempotency key before the first request.
  2. Send the request with explicit client timeouts.
  3. If the connection fails or a retryable server response occurs, retry with the same key and body.
  4. If Dockt returns an idempotency conflict, don’t generate a new key automatically. Determine whether the request changed or the first request is still active.
  5. Store the returned Dockt resource ID with the key after success.