Skip to navigation
Build your integration

Retry safely with request keys

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

View as Markdown

If a response is lost after you send a create, you can’t tell whether Truvo accepted it. Send the same request again with the same request key. If Truvo accepted the first one, it returns that request instead of starting a second.

Which requests need a key

These operations require the Idempotency-Key header:

OperationHTTP
Start a quote requestPOST /v1/quote-requests
Create a webhook subscriptionPOST /v1/event-subscriptions
Rotate a signing secretPOST /v1/event-subscriptions/{id}/rotate
Send a test eventPOST /v1/event-subscriptions/{id}/test
Replay a deliveryPOST /v1/event-subscriptions/{id}/replay

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, such as a UUID, for each new operation, and keep it so that a retry sends the same key:

KEY=$(uuidgen)
curl -X POST https://api.truvo.com/v1/quote-requests \
  -H "Authorization: Bearer $TRUVO_API_KEY" \
  -H "Truvo-Version: 2026-09-26" \
  -H "Idempotency-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d @quote-request.json

What happens when you send a key again

You sendThe API returns
The same key and the same bodyTruvo checks your current authority first, and it doesn’t start a second request. A quote request comes back as it is now, with the same id and its current status, version, and quotes, so the answer can differ from the first one.
The same key and a different body409 with the code request_key_reused and the retry action use_new_request_key. Truvo doesn’t ask any carrier.
A quote request with the same key while the first call with that key is still runningTruvo waits for the first call to finish, then answers as above. If the first call takes more than a few seconds, 409 with the code conflict and the retry action retry, and Truvo stores nothing for this call.

A key’s scope is one environment, one integration, one resource, and one operation. A key replays for at least 24 hours.

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

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 with the retry action retry. The first call with this key was still running. Wait for the time in Retry-After, then send the same body with the same key.
  • 409 request_key_reused with the retry action use_new_request_key. Your body is different from the first request with this key. To make a new request, use a new key.