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

# Idempotency

> How to repeat a write without writing the resource twice.

The network can fail after the API writes a resource and before the response reaches your system. In that case, your system does not know if the write happened. With the `Idempotency-Key` header, your system repeats the call, and the API writes the resource only once.

The header is optional. It applies to every `POST` of the API and to `PATCH /documents/{id}` with a file. Send the header in each of these calls.

## How to use it

1. Create a unique value for each write. A UUID works.
2. Keep the value with the write in your system.
3. Send the value in the `Idempotency-Key` header of the call.
4. If the response does not arrive, repeat the call with the same value and the same content.

```bash theme={null}
curl https://app.useqx.com/api/v1/contacts \
  -H "Authorization: Bearer qx_sua_chave" \
  -H "Idempotency-Key: 5f0c7e8a-3a1b-4d2e-9c61-2b7f4e0d9a13" \
  -H "Content-Type: application/json" \
  -d @contato.json
```

## What the API does with the value

The API compares each call with the first call that used the same value. The comparison uses the method, the path, the parameters, and the name and the content of each file. The order of the fields in the body does not change the comparison.

| Situation | Response |
| - | - |
| The value is new. | The API runs the call and keeps the response. |
| The value already served a call with the same content. | The API returns the kept response, with the same status, the same body and the same `Location` header. The API writes nothing new. |
| The value already served a call with different content. | `422` with the code `idempotency_key_reused`. |
| Another call with the same value is still in progress. | `409` with the code `idempotency_key_in_use`. |

## What to do with each error

| Status | `code` | What to do |
| - | - | - |
| 409 | `idempotency_key_in_use` | Wait a few seconds. Then repeat the call with the same value. |
| 422 | `idempotency_key_reused` | Your system used the same value in two different writes. Create a new value for the new write. |

## Responses that the API keeps

The API keeps the success response (`2xx`) and the `409` and `422` errors of the resource. A repeated call returns that response as it came the first time. To correct a call that got `409` or `422`, use a new value.

The API does not keep the other responses, such as `400`, `401`, `402`, `403`, `404`, `413`, `429` and `5xx`. It also does not keep the `idempotency_key_in_use` and `idempotency_key_reused` errors, or the `422` of a request outside the contract. See [Errors](/en/errors). A repeated call without a kept response runs again.

## Rules

* The value has 1 to 255 characters. A longer value gets `400` with the code `invalid_parameter`.
* `PATCH /documents/{id}` with `fields` ignores the value. The API runs each call with `fields` as a new call.
* Each API key has its own values. Two API keys can use the same value without a conflict.
* A repeated call that gets the kept response does not use a paid write. The call counts toward the limit of calls per minute.
* The API keeps the response for 24 hours. After that period, the API can delete the response. A call with the same value then runs as a new call.