Principles

Idempotency

Idempotency is implemented with the x-idempotency-key header, carried on both directions of the external API.

Calls into LightCMS (Provided API)

x-idempotency-key is optional and accepted on the card lifecycle endpoints and on the token read endpoints.

On the ingest endpoints (cardCreateResponse, holdEventResponse, subjectUpdate, accountUpdate), it acts as a deduplication key: resending the same key is a no-op that still returns 2xx. If it's omitted, no deduplication happens.

Calls out of LightCMS (Required API)

x-idempotency-key is always sent and required on every call LightCMS makes to the external system. It is derived per message in the form D-<uuid>.<n>. The external system must treat repeated keys as the same logical request. On retryable failures, LightCMS retries the same key: POST endpoints get 1 initial attempt + 4 retries (1 s apart, 10 s timeout); GET endpoints get 1 initial attempt + 3 retries (1 s apart, 10 s timeout). If the last attempt fails, the message is dead-lettered.

400, 401, 403 and 404 responses are not retried — the message is dead-lettered at once.

Tracing

Tracing information is carried by the X-Dobito-TraceId header. Both directions also support the generic traceparent W3C trace context header, propagated end to end wherever it's present on the originating message.

X-Dobito-TraceId carries the LightCMS trace id — 32 lowercase hex characters, the trace-id field of W3C traceparent (e.g. 6aa320f79fb62abf913622d14b42fc6a). It identifies an operation and is shared by every message of it. It is not a pairing key: requests and their asynchronous results are matched by the identifiers in the body (e.g. card.cardId, authcoreHoldId / externalHoldId).

Calls into LightCMS (Provided API)

X-Dobito-TraceId is optional and can be sent on any endpoint. When you report the outcome of an asynchronous request via POST /v3/cards/cardCreateResponse / POST /v3/holdEventResponse, echo the X-Dobito-TraceId of the originating POST /v3/cardCreateRequest / POST /v3/holdEventRequest request, so the result continues the original trace. On error responses that follow the Problem Details contract, the response body includes a traceId field (alongside tenant) to help diagnose the failing request.

Calls out of LightCMS (Required API)

X-Dobito-TraceId is sent on every call LightCMS makes to the external system whenever the originating message carries trace context. It is never sent as an empty header.