Request workflow transitions idempotently

Use transition requests when an integration must start a workflow transition asynchronously and track its outcome reliably. 202 Accepted confirms only durable acceptance. Read the business outcome from the returned statusUrl.

Send the request

Include a non-empty X-Idempotency-Key of no more than 255 characters:

http
POST /api/v1/workflows/transition-requests HTTP/1.1
Authorization: Bearer <token>
X-Tenant-ID: <tenant-uuid>
X-Idempotency-Key: order-4711-confirm-v1
Content-Type: application/json

{
  "entity": "order",
  "entityId": "<order-uuid>",
  "transition": "confirm"
}

The workflow endpoint accepts a request body of up to 1 MiB. PIM lifecycle adapters accept up to 64 KiB. Larger requests return 413 Request Entity Too Large and create neither a transition request nor a queue event.

Handle retries correctly

Reuse the same key while the tenant, endpoint, and business request remain unchanged. An exact retry returns 202 Accepted with the same requestId, status, and statusUrl. Concurrent retries also create only one request and one queue event.

Do not reuse a key for another entity, transition, or payload. Workspace returns 409 Conflict with ERR_IDEMPOTENCY_MISMATCH. Generate a new key only for a new business request.

A missing key returns 400 Bad Request with ERR_IDEMPOTENCY_KEY_REQUIRED. Treat this response as an integration error, not as a transient retry.

Evaluate status

Read statusUrl until the request reaches a terminal state:

  • pending: accepted but not claimed,
  • processing: durable processing is running,
  • succeeded: the workflow transition completed successfully,
  • failed: processing failed terminally.

Treat only succeeded as business success. Do not log an idempotency key when it contains business or customer data; use an opaque reference generated by your integration.