Networks fail. If a request times out you cannot tell whether Cerium received it. Retrying a plain request could create a second conversation or send the same message twice. An idempotencyKey solves this. Send a unique key with a request; if Cerium has already seen the key it returns the original result instead of repeating the work.

How it works

Where to use it

POST /customers does not need one: it is already create-or-get.

Choosing a key

  • Up to 64 characters.
  • Unique per message, and stable across retries of that message.
  • Derive it from something you already have, such as order-1042-msg-2, a message row id, or a UUID you store with the message before sending.
Do not generate a new key on each retry: that defeats the point. Create it once, store it, and reuse it for every attempt at the same message.

A retry pattern

Only retry on network errors, 429 and 5xx. A 4xx means the request itself is wrong and will fail again.