> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stockly.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Idempotency

> Safely retry reward requests without creating duplicates.

Giving stock is **idempotent**, controlled by the `idempotencyKey` you supply on
`POST /v1/rewards`. This makes retries — after a timeout, network blip, or double-click —
safe.

## How it works

* Generate a **fresh `idempotencyKey` per stock award** (a UUID is ideal). Reuse the
  *same* key when retrying that same award.
* The key is unique per app and must be 8–128 characters.

<ResponseField name="First request" type="201 Created">
  The award is created. `idempotentReplay` is `false`.
</ResponseField>

<ResponseField name="Retry with the same key and same payload" type="200 OK">
  The original award is returned unchanged and `idempotentReplay` is `true`. No duplicate
  is created.
</ResponseField>

<ResponseField name="Same key, different payload" type="409 Conflict">
  Returns a `conflict` error — a key can't be reused for a different award.
</ResponseField>

Concurrent duplicate requests are handled safely too: exactly one award is created, and the
others receive it as a replay.

<Tip>
  Persist the `idempotencyKey` alongside whatever triggered the award (e.g. an order id), so
  a retry naturally reuses the same key.
</Tip>