| Events | transaction_id in the event. The SDKs generate one when you omit it. | Returns the stored event. On the ClickHouse event store a repeat can be deduplicated only when transaction_id and timestamp both match, so send a timestamp and keep it: an event without one is stamped when it arrives. | 409 transaction_id_conflict when the code, subscription, properties or a sent timestamp differ from the stored event. The ClickHouse event store does not compare them: an event with another timestamp counts as a second event. |
Credit usage (usage.track) | Idempotency-Key header, required, up to 255 bytes. | Returns the original result, including a denial. A denial is also idempotent, so use a new key after adding credits. | 409 idempotency_key_reused. |
| Checkout, subscription changes, Entity subscriptions | Idempotency-Key header. | A replay of an accepted quoted request returns the original result, even after the quote expires. A new-subscription checkout retried while the first attempt is unpaid returns 422 subscription_incomplete even with the same key. | 409 idempotency_key_reused on checkout and subscription changes; 422 with idempotency_key_reused on Entity subscriptions. |
| Credit top-up purchase, billing state import, opening balance import, Entity credit transfers, Entities | Idempotency-Key header. Required on the top-up purchase, the billing state import and the opening balance import. | Returns the original result. An opening balance replay returns the imported values even if credits were used since. | 422 with idempotency_key_reused on the billing state import; a conflict (409) on the others. |
| Check & Deduct Credits (deprecated) | Nothing: not idempotent. An Idempotency-Key header is ignored. | Deducts again. Do not retry an uncertain result; read the credit balance first, or move to usage.track. | Not applicable. |
