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

# Idempotency — retry writes without creating duplicates

> How the Idempotency-Key header works on the 2Fin REST API and the Integration API: which requests it covers, how long keys last, what a replay looks like, and the limits of each store.

A network error halfway through a write leaves you not knowing whether it landed. Send an `Idempotency-Key` header and you can simply send the same request again: the second attempt returns the first answer instead of doing the work twice.

```bash theme={null}
curl -X POST https://api.ai2fin.com/api/bills \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f1c2a7e-8a4b-4f0e-9d6a-2b1e5c7d9a10" \
  -d '{ "name": "Electricity", "amount": 312.40, "dueDate": "2026-11-28" }'
```

Generate a fresh key (a UUID works well) for each distinct write, and reuse it only when retrying that same write.

There are two implementations, one for each surface. They share the header name and the 24-hour lifetime, and differ in where keys are stored.

## REST API (`/api/...`)

| | |
| - | - |
| Methods | `POST`, `PUT`, `PATCH`. `GET` and `DELETE` are already safe to repeat and are not tracked. |
| Opt-in | Requests without the header run normally. |
| Key | Any string up to 256 characters. Longer keys get `400`. |
| Scope | Your account plus the key, so two accounts can never collide. |
| Lifetime | 24 hours from the first response. |
| Replay | Same key and same body: the stored status and body come back with the header `Idempotency-Replay: true`, and the request does not run again. |
| Conflict | Same key with a different body: `409` with `"Idempotency-Key already used with a different request body"`. The comparison uses the first 2 KB of the serialised body. |

Whatever the first response was is what gets replayed, including an error. If a request failed because of something you then fixed, send the corrected request with a new key.

> [!WARNING]
>
> On the REST API the key store is held in memory by the server instance that answered. It is lost on a restart or deploy and is not shared between instances, so a retry that reaches a different instance runs again. Treat it as protection against quick client retries, not as a durable guarantee. For a create that must never duplicate, `POST /api/bank/transactions` also accepts a `clientRequestId` field (8–64 letters, digits or dashes) that is stored with the transaction itself: sending it again returns the saved row with `replayed: true`.

A few routes do not go through the REST store: the chat routes (`/api/chat/...`), receipt analysis and commit (`/api/receipts/...`), and the MCP endpoint (`/mcp`, which is outside `/api`). The API reference lists the `Idempotency-Key` parameter on every operation where it applies.

## Integration API (`/api/integrations/v1`)

The Integration API keeps its keys in the database, so they survive restarts and are shared by every instance.

| | |
| - | - |
| Endpoints | `POST /transactions`, `POST /statements`, `POST /expenses` |
| Key | 1–128 characters of letters, digits, `_`, `.`, `:` or `-`. A key outside that pattern is ignored and the request runs without idempotency. |
| Scope | Your account, the endpoint and the key. |
| Lifetime | 24 hours. |
| Replay | A completed request with the same key returns its stored response with `200` and `Idempotency-Replayed: true`. |
| In progress | If the first request with that key has not finished, you get `409` with `errorType: "IDEMPOTENCY_IN_PROGRESS"`. Retry shortly. A reservation left by a request that never finished is released after 90 seconds. |
| Failures | A failed request releases its key, so a retry with the same key runs. A batch that was only partly stored, or deferred, is also released so the retry picks up the rest. |

Statement imports are idempotent in two more ways: the same file sent again is recognised by its contents and not imported twice, and entries already stored are skipped by their own ids.

## Undo is separate

Idempotency stops a retry from doubling a write. To reverse a batch edit after it happened, see the data history endpoints (`GET /api/data-history`, then `GET /api/data-history/change-sets/{id}` to preview and `POST /api/data-history/change-sets/{id}/undo` to undo), which work for 30 days after the batch.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.