Idempotency

Certain endpoints in this API support idempotency to prevent duplicate actions when the same request is unintentionally repeated. Endpoints that support idempotency will explicitly mention this capability in their documentation.

How the IDEMPOTENCY_KEY Works

• Uniqueness Requirement: The IDEMPOTENCY_KEY must be unique to the action being performed. Specifically, it should be unique in combination with the organization ID and the action details. This ensures that the key uniquely identifies a specific operation within the organization.

• Validation Process: When a request is received with an IDEMPOTENCY_KEY, the system checks the key against previous requests for the same action and organization:

  • If the operation associated with the given IDEMPOTENCY_KEY has already been successfully performed, the API will return the same response as originally provided, avoiding any repeated action.
  • If a duplicate action is detected, the API will return a 409 Conflict response, along with an error message indicating that the action has already been processed. Client's should handle this response gracefully.

Workflow

1. Initial Request: When the client sends a request with a new IDEMPOTENCY_KEY, the API processes the action and stores the outcome.
2. Subsequent Duplicate Request: If the client sends the same request again with the same IDEMPOTENCY_KEY, the API recognizes it as a duplicate and returns a 409 Conflict response with an error message, allowing the client to handle it gracefully.

Header Example

IDEMPOTENCY_KEY: 123e4567-e89b-12d3-a456-426614174000

• The IDEMPOTENCY_KEY value can be any unique string. A common pattern is to combine identifiers that are unique to the action being performed (e.g., the user ID and an action-specific ID).