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

# Idempotent POST requests with the Idempotency-Key header

> Attach an Idempotency-Key header to POST and batch requests to replay results safely on retry, avoiding duplicate operations and double-counting.

The 8bitedge API supports idempotent POST requests via the `Idempotency-Key` request header. When you attach a unique key to a request, the server stores the response. If you send the same key again with the same payload — for example after a network timeout left you unsure whether your original request succeeded — the server replays the original response byte-for-byte rather than processing the request a second time. This lets you retry safely without risk of double-counting, duplicate batch submissions, or other unwanted side-effects.

## How it works

* **Generate a UUID per logical operation** and attach it as the `Idempotency-Key` header on your POST or batch request.
* **A repeat with the same key and the same payload** returns the stored response with an `Idempotency-Replayed: true` response header, confirming that no new work was performed.
* **Stored responses expire after 24 hours.** After that window, submitting the same key is treated as a fresh request.
* **Idempotency applies to POST and batch requests only.** GET requests are naturally safe to retry without a key.

## Step-by-step example

<Steps>
  <Step title="Generate a UUID for the operation">
    Create a UUID v4 to use as your idempotency key. On most Unix systems you can use `uuidgen`:

    ```bash theme={null}
    KEY=$(uuidgen)
    echo $KEY
    # e.g. 4f8b2c3d-1a2b-4e5f-9c0d-7e8f1a2b3c4d
    ```

    Store this key alongside your operation record so you can replay it if something goes wrong later.
  </Step>

  <Step title="Send the initial request with the key">
    Attach the UUID as the `Idempotency-Key` header on your POST request:

    ```bash theme={null}
    KEY=$(uuidgen)
    curl -s -X POST "https://api.8bitedge.com/api/v1/signals/batch" \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: $KEY" \
      -d '{ "requests": [ { "id": 1 } ] }' | jq
    ```

    The API processes the request normally and stores the response keyed to your UUID.
  </Step>

  <Step title="Retry on network error">
    If the request fails mid-flight — a timeout, dropped connection, or any other network error — you can safely retry using the exact same key and the exact same payload:

    ```bash theme={null}
    # Safe to retry on a network error — same key + body replays the stored result:
    curl -s -D - -X POST "https://api.8bitedge.com/api/v1/signals/batch" \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: $KEY" \
      -d '{ "requests": [ { "id": 1 } ] }' \
      -o /dev/null | grep -i idempotency-replayed
    ```

    The API returns the original response without executing the operation a second time.
  </Step>

  <Step title="Verify the Idempotency-Replayed header">
    When the API detects a matching key + payload and serves a cached response, it sets `Idempotency-Replayed: true` in the response headers. Confirm this in your retry logic to be sure you received a replayed result rather than a fresh one:

    ```text theme={null}
    Idempotency-Replayed: true
    ```

    If this header is absent, the request was processed fresh — either the key was new or the cached response had expired.
  </Step>
</Steps>

## Error cases

| Status | `code`                  | When                                                                                   |
| ------ | ----------------------- | -------------------------------------------------------------------------------------- |
| 409    | `idempotency_conflict`  | The same key is still in flight — the original request has not yet finished processing |
| 422    | `idempotency_key_reuse` | The same key was submitted with a different payload                                    |

If you receive a `409 idempotency_conflict`, the original request is still being processed. Wait briefly and retry — the stored response will be available once it completes.

If you receive a `422 idempotency_key_reuse`, you have submitted a key that was previously used with a different request body. Generate a new UUID for the new operation; never repurpose a key.

## Best practices

* **Use a UUID v4 per logical operation.** UUIDs are statistically unique and inexpensive to generate. Create a fresh one for each distinct operation — not per retry.
* **Never reuse a key with different payloads.** Each key is bound to the payload it was first submitted with. Sending a different body with the same key will always return `422 idempotency_key_reuse`.
* **If you get a `409`, wait briefly and retry.** A conflict means your original request is still being processed. A short wait (a few seconds) is usually enough for the result to be stored.

<Tip>
  Persist your idempotency key in your own database alongside the operation it represents — before you send the request. If your process crashes mid-flight, you can look up the key and replay the exact same request to recover safely, without having to guess whether the original request succeeded.
</Tip>