> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bedrock.cv/llms.txt
> Use this file to discover all available pages before exploring further.

# Idempotency

> Safely retry requests without creating duplicate resources.

All `POST` endpoints accept an `Idempotency-Key` header. If two requests share the same key, the second returns the cached response from the first instead of creating a duplicate resource.

This is critical for Vision API operations that consume [credits](/api-reference/credits). A network timeout during `POST /compare` shouldn't cost you twice.

## Usage

Pass a unique key (we recommend UUIDv4) in the `Idempotency-Key` header:

```bash theme={null}
curl -X POST https://api.bedrock.cv/compare \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c4a8d09-ca72-4053-98b2-6a76c3b4e8f1" \
  -d '{"old_id": "blk_01JABCD100", "new_id": "blk_01JABCD200", "type": "Block"}'
```

If the request succeeds, any subsequent request with the same key returns the original `202` response — no new job is created and no credits are charged.

## Behavior

| Scenario                                  | Result                                           |
| ----------------------------------------- | ------------------------------------------------ |
| First request with key                    | Processed normally                               |
| Duplicate key, original succeeded         | Returns cached response (same status, same body) |
| Duplicate key, original still processing  | Returns cached `202` with the original `job_id`  |
| Duplicate key, original failed with `4xx` | Returns cached error (no retry)                  |
| Duplicate key, original failed with `5xx` | Allows retry (key is released)                   |

## Key Rules

* Keys are scoped to your **organization**. Two different organizations can use the same key.
* Keys expire after **24 hours**. After expiry, the same key can be reused.
* Keys must be between 1 and 256 characters (alphanumeric, hyphens, and underscores).
* Sending a different request body with an existing key returns a `409 Conflict` error.

## Response Headers

When a cached response is returned, the response includes:

```
Idempotency-Status: hit
```

On the first request:

```
Idempotency-Status: miss
```

## When to Use

Use idempotency keys on any `POST` that creates resources or starts jobs:

* `POST /drawings` — prevent duplicate drawing processing
* `POST /drawings/{id}/compare` — prevent duplicate comparisons
* `POST /compare` — prevent duplicate analysis
* `POST /parse` — prevent duplicate parsing

You don't need idempotency keys on `GET`, `PATCH`, or `DELETE` — these are naturally idempotent.

## Example: Retry with Idempotency

```python theme={null}
import requests
import uuid

key = str(uuid.uuid4())

def create_comparison():
    return requests.post(
        "https://api.bedrock.cv/drawings/drw_01JABCD123/compare",
        headers={
            "Authorization": "Bearer sk_xxx",
            "Idempotency-Key": key,
        },
        json={"compare_to": "drw_01JABCD456"},
        timeout=10,
    )

# First attempt — may timeout
try:
    response = create_comparison()
except requests.Timeout:
    # Safe to retry with the same key
    response = create_comparison()

# Guaranteed: only one comparison job was created
print(response.json()["job_id"])
```