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

# Retries and idempotency

> Retry public POST requests without repeating an operation

## Retry the same action

Public POST requests accept an optional `Idempotency-Key` header. If a response is lost, retry the same request with the same key to avoid repeating the operation.

Use a new random UUID for each intended action, enclosed in double quotes inside the header value:

```bash theme={null}
curl -X POST 'https://api.qontext.ai/v1/folders' \
  -H "Authorization: Bearer $QONTEXT_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: "8e03978e-40d5-43e8-bc93-6894a57f9324"' \
  -d '{"name":"Projects"}'
```

Send the header once. The decoded key must contain 1–255 ASCII characters. A missing quote, a malformed value or a repeated header returns `400 invalid_request`.

## Reuse keys for retries

A key belongs to one workspace and API credential. For **24 hours**, the same key and request replay the original status and body. Keep the HTTP method, path, query parameters and body unchanged.

Use a different key for a separate intended action, even when its content is identical. After the 24-hour retention period expires, the same key can execute again.

> [!WARNING]
>
> Saved responses include temporary errors and `5xx` failures. A `5xx` does not prove that the operation had no effect. Repeating it with a new key can create a duplicate; check the live state before starting a replacement action.

## Handle retry errors

| Response | What to do |
| - | - |
| `409 idempotency_conflict` | The original request is still running or its outcome is unresolved. Wait and retry with the **same key**. If the conflict persists, check the live state. After the key's 24-hour retention period expires, a retry can execute the operation again. |
| `422 idempotency_mismatch` | The key was used for a different request. Restore the original request for a retry, or use a new key for a separate intended action. |

Replays check current resource permissions. A denied replay does not execute the operation again or erase the saved result. The error body's request ID can belong to the original request; the `X-Request-Id` header identifies the current attempt.

## Content updates

`PUT /v1/files/{id}/content` is not covered by this header. Follow [Updating content](https://docs.qontext.ai/api-docs/updating-content.md#recover-after-an-interrupted-request) to inspect the live state and changes in review after an interrupted content update.


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