---
title: "Idempotency"
description: "Use Idempotency-Key to recover stored POST responses and reconcile uncertain outcomes; clientReferenceId helps match API objects to your records."
url: "/guides/api-basics/idempotency/"
index: "/llms.txt"
---

# Idempotency

A network failure can leave you without a response, so you do not know whether Nodu processed your request. An idempotency key lets you recover a stored successful response to the same `POST` request. Nodu keeps that response for 24 hours. After an uncertain outcome, check whether the operation completed before retrying: see [Retry a request that timed out](#retry-a-request-that-timed-out). Your own `clientReferenceId` can help match the result to your records and complement idempotency handling.

## Send an idempotency key

Add the `Idempotency-Key` header to a `POST` request:

```text
Idempotency-Key: 8f14e45f-ceea-467f-a9d1-8b0c2f1d3a77
```

- The value is a string that you choose, up to 255 characters long. Nodu refuses a longer value with a `422` validation error.
- Use a new value for each operation. A version 4 UUID is a good choice. Two transfers with the same body need two keys: with one key, the second request returns the first transfer.
- Nodu applies the header to `POST` requests only. On `GET`, `PUT`, `PATCH` and `DELETE` requests Nodu ignores it.
- The header is optional. Without it, Nodu processes every `POST` request as a new request.

Send the header with every `POST` request that creates an object or moves money, such as [Create a customer](/api/tag/customers/post-v1-customers.md) and [Create a transfer](/api/tag/transfers/post-v1-transfers.md).

## How Nodu handles a key

| Request | What Nodu does |
|---|---|
| The first request with a key | Processes the request. If it succeeds, Nodu stores the request body and the response for 24 hours. |
| A stored successful result, with the same key and body, within the 24 hours | Returns the stored response, with the same status code and the same body. Nodu does not perform the operation again. |
| A stored successful result, with the same key but a different body, within the 24 hours | Refuses the request with `409 Conflict` and `code=idempotency_mismatch`. Restore the original body to recover the stored response. |
| The same key after the 24 hours | Processes the request as a new request. |

Two details decide whether Nodu treats a request as a repeat:

- **Nodu compares the body exactly as you sent it.** The same JSON with different spacing or a different field order counts as a different body.
- **A key belongs to the API key and the endpoint that it was sent to.** The same value sent with another API key, or to another endpoint, is a new key for Nodu. Retry with the same API key you used for the first request.

A `409` with `code=resource_busy` can mean an earlier request with the same key is still running. Other resource conflicts have their own recovery actions: see [Errors and rule codes](/guides/api-basics/errors-and-rule-codes/index.md).

## When Nodu does not store a result

Nodu stores a result only when the request succeeds, that is, when the response status is `2xx`. Nodu does not store an error response. When no successful response is stored, a retry is processed again. An operation can complete before its response fails, so a server error does not prove that nothing happened.

- After a validation error or a business rule violation, correct the cause. Send the request again with the same idempotency key or a new one.
- A request that arrives while Nodu is still processing an earlier request with the same key waits for it. If the earlier request is still running after the wait, Nodu answers `409` with `code=resource_busy` and a `Retry-After` header. Send the request again with the same key and exact body.

## Retry a request that timed out

When a `POST` request times out, the connection drops, or Nodu returns `500`, the outcome is unknown. Before the first request, store the idempotency key, the exact request body and your reference for the operation.

Check the resource's current state, list results and webhook events before retrying. For transfers, follow [Reconcile with the list](/guides/transfers/track-a-transfer/index.md#reconcile-with-the-list). An operation can complete without a stored successful response; retrying even with the same key can then perform it again. If you cannot establish the outcome, contact Nodu before creating a replacement or releasing reserved funds.

When you retry, use the same key, API key, endpoint and exact body within 24 hours:

- If Nodu stored a successful response, you receive that response without repeating the operation.
- If no successful response is stored, Nodu processes the request again.

Do not create a new key to recover an uncertain result. After 24 hours, the stored response expires: reconcile before sending another request, even with the original key.

## Use `clientReferenceId` with idempotency

`clientReferenceId` is an identifier from your own system, such as your internal id of the customer. You send it in the body of a create request. Nodu stores it with the object and returns it in the object. Unlike an idempotency key, it does not expire.

Use a stable value from your records to connect a request, its response and later webhook events. Keep the returned Nodu `id` alongside it. The API Reference describes each operation's reference constraints and available filters.

Continue to use `Idempotency-Key` for retries: it returns a stored successful response within the retention period. If an operation returns `resource_conflict`, check the existing object before deciding whether to create another one.

## Retry decisions

| Result | Next action |
|---|---|
| Timeout, dropped connection or `500` | Reconcile the outcome first. When retrying, use the same key and exact body within 24 hours; contact Nodu if the outcome remains uncertain. |
| `409` with `code=resource_busy` | Wait the number of seconds in `Retry-After`, then retry with the same key and exact body. |
| `409` with `code=idempotency_mismatch` | Restore the original body to recover its result. Use a new key only for an intentionally separate operation. |
| Validation error or business rule violation | Correct the input or resolve the state conflict before trying again. |
| Another `resource_conflict` | Follow the recovery action in [Errors and rule codes](/guides/api-basics/errors-and-rule-codes/index.md). |
| Key older than 24 hours | Reconcile first; the expired key no longer protects a retry. |

## Next steps

- [Errors and rule codes](/guides/api-basics/errors-and-rule-codes/index.md): which errors to retry.
- [Track and cancel a transfer](/guides/transfers/track-a-transfer/index.md#reconcile-with-the-list): find a transfer whose create request you could not confirm.
- [Quickstart: your first sandbox transfer](/guides/get-started/quickstart/index.md): send your first `POST` requests in the sandbox.
