> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.truvo.com/guides/request-keys/llms.txt.

# Retry safely with request keys

Networks drop responses. If that happens after you send a create, you can't tell whether Truvo accepted it. A request key fixes that: send the same request with the same key, and Truvo returns the original result instead of starting a second request.

## Which requests need a key

These operations require the `Idempotency-Key` header:

| Operation                     | HTTP                                       |
| ----------------------------- | ------------------------------------------ |
| Start a quote request         | `POST /v1/quote-requests`                  |
| Create a webhook subscription | `POST /v1/event-subscriptions`             |
| Rotate a signing secret       | `POST /v1/event-subscriptions/{id}/rotate` |
| Send a test event             | `POST /v1/event-subscriptions/{id}/test`   |
| Replay a delivery             | `POST /v1/event-subscriptions/{id}/replay` |
| Select a sandbox scenario     | `POST /v1/sandbox/scenarios`               |
| Reset the sandbox             | `POST /v1/sandbox/reset`                   |
| Run a sandbox control         | `POST /v1/sandbox/controls`                |

Reads don't take a key.

## Choose a key

A key is 1 to 255 characters long, made of letters, digits, `.`, `_`, `:`, and `-`. Use a new key for each new request. A UUID works well:

```bash
curl -X POST https://api.truvo.com/v1/quote-requests \
  -H "Authorization: Bearer $TRUVO_API_KEY" \
  -H "Idempotency-Key: 6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f" \
  -H "Content-Type: application/json" \
  -d @quote-request.json
```

## What happens when you send a key again

| You send                          | The API returns                                                                                           |
| --------------------------------- | --------------------------------------------------------------------------------------------------------- |
| The same key and the same body    | The original result. Truvo checks your current authority first, and it doesn't start a second request.    |
| The same key and a different body | `409` with the code `conflict` and the retry action `use_new_request_key`. Truvo doesn't ask any carrier. |

A key's scope is one environment, one integration, one resource, and one operation.

Over MCP, `request_insurance_quotes`, `send_test_event`, and `replay_event_delivery` take the key in their `request_key` argument, with the same rules.

A key replays for at least 24 hours.

## When to retry

* **A timeout or a network error.** Send the same body with the same key.
* **`503` with the retry action `retry`.** Wait for the time in `Retry-After`, then send the same body with the same key.
* **`409` `conflict`.** Your body is different from the first request with this key. To make a new request, use a new key.

> Send an Idempotency-Key with every create, so a retry never starts a second request.