Available nowIn progressLast updated: June 2026

Idempotency

Idempotency makes event ingestion safe under retries. It helps prevent duplicate operational records when clients retry after timeouts, network failures, or unknown request outcomes.

Use a stable event_id

When the producer already has a unique event identifier, send it as event_id for traceability and replay.

Send an Idempotency-Key

Use the Idempotency-Key header for request-level duplicate protection, especially when retrying after timeouts.

Reuse the same key on retry

If the first request outcome is unknown, retry with the same Idempotency-Key instead of generating a new one.

Scope duplicates by source

Duplicate detection should be based on source identity plus idempotency key or event id, not only the raw event id.

Recommended duplicate key

Deduplication should be based on the source identity plus the Idempotency-Key or event_id. This avoids collisions when different producers use similar identifiers.

source_id + idempotency_key / event_id

Example retry-safe request

If this request times out, retry with the same Idempotency-Key.

curl -X POST "https://api.laribacloud.com/v1/events/ingest" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_SOURCE_API_KEY" \
  -H "Idempotency-Key: payment-failed-evt-001" \
  -d '{
    "event_id": "evt_payment_failed_001",
    "event_type": "payment.failed",
    "source_id": "src_payments",
    "environment": "production",
    "payload": {
      "amount": 49.99,
      "currency": "EUR",
      "reason": "card_declined"
    }
  }'

Common scenarios

Scenario	Expected behavior
Network timeout	The client does not know whether the event was stored. Retry with the same Idempotency-Key.
Producer retry	The producer retries the same operation. Lariba Cloud should avoid creating duplicate operational records.
Same event id from different sources	Different sources may reuse event ids. Source identity prevents collisions across producers.
Changed payload under same key	This should be treated carefully. Future hardening may compare payload hashes to detect inconsistent retries.

Best practice: send both a stable event_id and an Idempotency-Key when possible. This improves traceability and retry safety.

Timeout rule: when the request outcome is unknown, retry with the same key instead of creating a new idempotency value.

Do not reuse the same Idempotency-Key for unrelated events. A key should represent one logical request or event delivery attempt.