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

# Idempotency

> Retry write requests safely with the Idempotency-Key header.

Endpoints that create data can accept an `Idempotency-Key` header, so you can retry them after a timeout or `5xx` without creating duplicates. An endpoint's reference page says whether it supports the header. They include:

* `POST /resumes`
* `POST /talent-network/candidates/submit`
* `POST /talent-network/candidates/submit-bulk`

```bash theme={null}
curl -X POST "https://external-api.paraform.com/api/external/v1/talent-network/candidates/submit-bulk" \
  -H "Authorization: Bearer $PARAFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5b0f3c1e-8d2a-4a51-9a0e-3f7a2f6c9e14" \
  -d @batch.json
```

## How it works

* Generate a unique value, such as a UUID, for each logical request. Send the **same** value when you retry that request.
* The first successful response is stored for **24 hours**. A retry with the same key and the same body gets the stored response back, including the original `batchId`, instead of running the request again.
* Keys are scoped to your API key and the endpoint, so the same value on a different endpoint or under a different key doesn't collide.
* If the first attempt fails with an error, nothing is stored, and a retry with the same key runs the request again.

## Conflicts

These cases return `409` with error type `idempotency_error`:

| Case | Message |
| - | - |
| Same key, different request body | `Idempotency-Key reused with a different request body` |
| Same key while the first attempt is still running | `A request with this Idempotency-Key is already in progress` |

Wait and retry the in-progress case. Fix the body-mismatch case by sending a new key.

## Endpoints that don't need it

Endpoints that don't support the header ignore it. Reads have no side effects, and some writes converge on the same state when retried, so they don't need it. For example:

* `PUT /talent-network/candidates/{candidateUserId}/preferences` and `PUT …/fast-track` set a value, so repeating them is harmless.
* `POST /talent-network/candidates/off-market` and `POST …/re-enable` report `already_off_market` or `already_on_market` on a repeat.


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