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

# Deduplication and Idempotency

> Prevent duplicate work with dedupe keys and idempotency keys.

## `dedupe`

`dedupe` deduplicates semantically identical actions in a 24-hour window.

* Scope: account + key
* Ignores already `failed` actions
* If matched, API returns existing action with `deduplicated: true`

### Typical use cases

* Prevent duplicate invoice processing
* Avoid repeated outbound notifications
* Suppress duplicate user-triggered operations

## `Idempotency-Key` header

`Idempotency-Key` deduplicates repeated create requests in a 24-hour window.

* Scope: account + header value
* Works even if body is retried by the client unchanged
* Returns existing action with `deduplicated: true`

## Difference

<Tabs>
  <Tab title="dedupe">
    Business-level dedupe: "these actions mean the same thing".
  </Tab>

  <Tab title="Idempotency-Key">
    Request-level dedupe: "this exact create call was retried".
  </Tab>
</Tabs>

## cURL examples

<CodeGroup>
  ```bash dedupe theme={null}
  curl -X POST http://localhost:3000/v1/actions \
    -H "Authorization: Bearer <API_KEY>" \
    -H "Content-Type: application/json" \
    -d '{
      "url": "https://example.com/work",
      "body": {"invoice_id":"inv_123"},
      "dedupe": "invoice:inv_123"
    }'
  ```

  ```bash Idempotency-Key theme={null}
  curl -X POST http://localhost:3000/v1/actions \
    -H "Authorization: Bearer <API_KEY>" \
    -H "Idempotency-Key: req-2026-03-16-001" \
    -H "Content-Type: application/json" \
    -d '{
      "url": "https://example.com/work",
      "body": {"invoice_id":"inv_123"}
    }'
  ```
</CodeGroup>