Skip to main content
Carbon’s pipeline is built so that events are never duplicated and retries are always safe — from the SDK buffer to durable storage.

​
The path of an event

  1. The SDK buffers events and sends them in batches — by count, size, or age. See Configuration.
  2. The ingest API authenticates the batch, validates every event, attaches your space, and enriches provider and cost.
  3. Each event is placed on a durable queue and the API responds 202 Accepted.
  4. A worker processes each event exactly once in effect: the full event is archived, and a lean analytics row is written for querying.

​
202 means queued

The ingest API acknowledges once events are durably queued, not once they are written to the analytics store. Processing typically completes within seconds; events then appear in the dashboard.

​
Idempotency

Every event is identified by its client-generated id, unique within your space. The first event to arrive with a given ID wins; any later event with the same ID is acknowledged and discarded. This makes retries safe at every layer:
  • The SDK retries failed batches without creating duplicates.
  • Your own HTTP retries against the ingest API are safe as long as you reuse the same event id.
  • Internal queue redeliveries (processing is at-least-once) are deduplicated before storage.
If you implement your own delivery, generate the event id once when the call happens — not per send attempt — so retries deduplicate correctly.

​
Ordering

Events are timestamped by your application (startTimeMs, endTimeMs), so analytics are ordered by when calls actually happened, not by when events arrived. Late delivery — a retried batch, a flushed buffer from a recovered process — lands in the right place on the timeline.

​
Usage limits

Plan limits are enforced at the API boundary: once a Free space reaches its monthly allowance, or a Plus subscription is inactive, the ingest API rejects the batch with 402 and a stable error id (usage_limit_exceeded or billing_not_active). The SDK reports these rejections through onError (or a throttled console warning) and drops the affected events instead of retrying — see Configuration. Enforcement is also applied during processing as a backstop, so batches already in flight when a limit is crossed may be partially rejected after a 202. Rejected events do not appear in the dashboard and are not billed. On Plus, events beyond the included amount are accepted and billed per event. See Plans and limits.