---
title: "Idempotency · API docs · CheckAnySite"
description: "Send an Idempotency-Key header with a POST request, and a retry returns the first response instead of charging you twice."
url: "https://docs.checkanysite.com/idempotency"
---

Concepts

# Idempotency

Send an `Idempotency-Key` header with a POST request, and a retry returns the first response instead of charging you twice.

## Send a key

After a network error, you can’t tell whether a POST request reached us. If you send it with an `Idempotency-Key` header, you can safely send it again: the API runs it only once. Every POST endpoint accepts the header, including scans and batches.

- Create a key for each operation you want to run once, such as a UUID. A key is 1 to 255 characters long.
- Send the same key, with the same body, each time you retry that operation.
- We keep each key for 24 hours per API key. After that, the same key starts a new request.

The following request starts a scan that is safe to retry:

```bash Terminal
# Create one key per scan, and send the same key each time you retry it.
KEY=$(uuidgen)

curl -X POST "https://api.checkanysite.com/v1/scans" \
  -H "Authorization: Bearer $CHECKANYSITE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -d '{"domain": "wikipedia.org", "checks": ["ai"]}'
```

The [Python SDK](https://docs.checkanysite.com/sdks/python) sends a key with every POST request automatically.

## Replayed responses

When you send the same key with the same body, the API returns the first request’s status and body, with an `Idempotent-Replayed: true` header. A replayed response is never charged, so a retried scan neither starts a second scan nor costs credits twice:

```text Replayed response
HTTP/2 202
Idempotent-Replayed: true
Location: https://api.checkanysite.com/v1/scans/0b5a7a6e-…

{"id": "0b5a7a6e-…", "status": "queued", …}
```

## When a key is refused

- `422` [idempotency\_key\_reused](https://docs.checkanysite.com/errors#idempotency_key_reused): the key was sent with a different body. Each key belongs to one request, so create a new key for a new request.
- `409` [idempotency\_key\_in\_use](https://docs.checkanysite.com/errors#idempotency_key_in_use): the first request with this key is still running. Retry a moment later with the same key to get its response.

Note

GET requests don’t need a key. Reading a stored result or a scan changes nothing, so it’s always safe to repeat.