Idempotency and retries

An idempotency key identifies one logical mutation. On routes using the shared helper, send Idempotency-Key with a nonempty value of at most 200 characters. Creation and execution handlers that support it replay completed status/body for the same request. A different payload under the same key conflicts; an uncertain in-progress operation must not be treated as a fresh request.

curl --fail-with-body -X POST \
  -H "Authorization: Bearer $SEMOGRAM_API_KEY" \
  -H 'Idempotency-Key: equipment-import-2026-10-05-001' \
  "https://platform.semogram.com/api/v1/projects/$SEMOGRAM_PROJECT_ID/pipelines/$SEMOGRAM_PIPELINE_ID/execute"

Reuse this key only to retry that logical run. Generate a new key for the next intended run. Persist the key before sending work and retain the returned resource/run ID.

Route-specific support

The route catalog identifies handlers using the shared helper. Other routes can have their own operation-level deduplication; do not assume every POST honors this header. Source-write POST explicitly requires it and stores durable operation state.

Deduplicating API submission does not promise exactly-once effects in every external connector. A pipeline can fail after an external write. Recovery still needs the connector's transaction, snapshot and policy behavior. Retry GET reads with bounded backoff; for mutation timeouts, first reconcile the known resource or operation.