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

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:

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
Select a sandbox scenarioPOST /v1/sandbox/scenarios
Reset the sandboxPOST /v1/sandbox/reset
Run a sandbox controlPOST /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:

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 sendThe API returns
The same key and the same bodyThe original result. Truvo checks your current authority first, and it doesn’t start a second request.
The same key and a different body409 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.