# 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:

```http
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](/docs/concepts/limits), 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_request` and other validation errors before resolution;
- `rate_limited`, `concurrency_limited`, `engine_busy` and `rate_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 as `engine_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}`, incrementing `n` only 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**

```bash
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
```

**Ruby**

```ruby
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))
```

**Python**

```python
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))
```

**JavaScript**

```javascript
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));
```

[Open this request in the console playground](https://data-services.autouncle.com/console/playground?example=valuation)

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](/docs/guides/polling-and-replay) for recovery patterns built on idempotency.
