AutoUncle Data Services is in beta. The API, MCP tools and agent skill may change often, including breaking changes, until version 1.0. Read the changelog before you upgrade an integration.
Idempotency
An idempotency key lets you repeat a valuation request without the risk of valuing, or paying for, the same vehicle twice. This page explains exactly how keys behave, so your retries are always safe.
Send a key
On REST, send the key as a header:
Idempotency-Key: listing-48213-rev-3
Over MCP, pass it as the idempotency_key argument of valuate_car. The behavior is the same.
A key is 1 to 200 printable ASCII characters, without spaces. Anything else is rejected with 400 invalid_request. The key is optional, but without one every request is a new valuation, and a retry after a lost response may be charged again.
What a key covers
A key belongs to your workspace and to the mode of the key that sent it. Two API keys of the same workspace and mode share keys; a test key and a live key never do. Reusing a key in another workspace has no effect on yours.
The service remembers the key together with a fingerprint of the request body. The fingerprint ignores the order of JSON object fields, so {"country":"DK","vehicle":{...}} and {"vehicle":{...},"country":"DK"} count as the same body. Any other change, including a different mileage by one kilometre, is a different body.
What happens on each call
| You send | Situation | Result |
|---|---|---|
| A new key | A new valuation is started and recorded. | |
| The same key and body | The first call finished (valued, refused or failed) |
The recorded outcome is returned again, with usage.idempotent_replay: true and usage.credits_used: 0. No new valuation, no charge. |
| The same key and body | The first call is still running | 409 request_in_progress. Wait briefly and send it again with the same key. |
| The same key, a different body | 409 idempotency_conflict. Nothing is recorded. Use a new key for a different request. |
A replay returns the original HTTP status and body. A recorded failure replays as the same failure: replaying does not try again. Notes and attributions are replayed as they were when the valuation was produced.
Replays still count towards your rate limit, but they do not need a concurrency slot.
Requests that were never recorded
Some errors happen before a valuation is recorded, so they do not use up the key:
- authentication, scope, country and credit errors;
invalid_requestand other validation errors before resolution;rate_limited,concurrency_limited,engine_busyandrate_limit_unavailable.
After fixing the cause, or after waiting retry_after seconds, send the same key and body again. It is treated as the first attempt.
When to use a new key
- Unknown outcome (timeout, dropped connection, a 5xx from a proxy without a Problem body): retry with the same key and body. If the first attempt finished, you get its result; if it never arrived, it runs now.
- Confirmed refusal: fix the input (for example add mileage) and send it with a new key. The old key would only replay the refusal, and the new body would conflict with it anyway.
- Confirmed failure (
failed, such asengine_timeout): wait, then send it with a new key for a fresh attempt. - A deliberate revaluation of the same vehicle later, for example next month: use a new key.
Choosing keys
Derive the key from what makes the valuation unique in your system, so a crash and restart produces the same key:
listing-{listing_id}-rev-{revision}for a listing that can change;{batch_id}-{row_number}for a batch file;{case_id}-attempt-{n}, incrementingnonly for deliberate new attempts.
A random UUID per intended valuation also works, as long as you store it before the first attempt and reuse it for retries.
Example
curl https://data-services.autouncle.com/v1/valuations \
-H "Authorization: Bearer $AUTOUNCLE_API_KEY" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: first-valuation-001' \
-d @- <<'JSON'
{
"country": "DK",
"vehicle": {
"make": "Volkswagen",
"model": "Golf",
"model_year": 2020,
"mileage": {
"value": 60000,
"unit": "km"
}
}
}
JSON
require "json"
require "net/http"
uri = URI("https://data-services.autouncle.com/v1/valuations")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer #{ENV.fetch("AUTOUNCLE_API_KEY")}"
request["Content-Type"] = "application/json"
request["Idempotency-Key"] = "first-valuation-001"
request.body = JSON.generate({
"country" => "DK",
"vehicle" => {
"make" => "Volkswagen",
"model" => "Golf",
"model_year" => 2020,
"mileage" => {
"value" => 60000,
"unit" => "km"
}
}
})
response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) }
puts JSON.pretty_generate(JSON.parse(response.body))
import json
import os
import requests
response = requests.post(
"https://data-services.autouncle.com/v1/valuations",
headers={
"Authorization": f"Bearer {os.environ['AUTOUNCLE_API_KEY']}",
"Idempotency-Key": "first-valuation-001",
},
json={
"country": "DK",
"vehicle": {
"make": "Volkswagen",
"model": "Golf",
"model_year": 2020,
"mileage": {
"value": 60000,
"unit": "km"
}
}
},
timeout=30,
)
print(json.dumps(response.json(), indent=2))
const response = await fetch("https://data-services.autouncle.com/v1/valuations", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.AUTOUNCLE_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": "first-valuation-001",
},
body: JSON.stringify({
country: "DK",
vehicle: {
make: "Volkswagen",
model: "Golf",
model_year: 2020,
mileage: {
value: 60000,
unit: "km"
}
}
}),
});
console.log(JSON.stringify(await response.json(), null, 2));
Run it twice: the second response has "idempotent_replay": true. Change the mileage and run it a third time with the same key: you get 409 idempotency_conflict.
See retrieve, replay & reconcile for recovery patterns built on idempotency.