# Idempotency and duplicates

Agents retry: a timeout, a lost response, a re-run step. Two tools keep a retry from posting twice.

## Idempotency-Key

Send `Idempotency-Key: <unique value>` (a UUID, or an id from your system; up to 255 characters) on `POST /v1/posts`, `POST /v1/connect`, `POST /v1/media` (JSON), `POST /v1/partner/workspaces`.

```
curl -X POST https://wyroapi.com/v1/posts \
  -H "Authorization: Bearer $WYRO_API_KEY" \
  -H "Idempotency-Key: 6f1c2a9e-3b7d-4c55-9e1a-0d2b8f4a7c11" \
  -H "Content-Type: application/json" \
  -d '{"text": "…", "platforms": ["instagram"], "media": [{"url": "https://…/a.jpg"}]}'
```

- The **same key with the same body** from the same workspace (or partner) within **24 h** returns the **first response** (same status and body) without doing the work again. It carries the header `Idempotent-Replayed: true`.
- The **same key with a different body** answers `409 idempotency_conflict`. If the first request is still running, also 409, with `details.reason: "in_progress"`: wait a second and retry.
- Answers that mean "try again" (`429` and `5xx`) are not stored: retrying with the same key runs the request again.
- Credentials are never stored: on `POST /v1/partner/workspaces`, a replay returns `api_key`, `webhook_secret` and `mcp_url` as `null` (rotate the key if you lost it).
- We store only hashes of the key and of the request, next to the response.

## Duplicate guard

`POST /v1/posts` refuses the **same text on the same account within 24 h** with `409 duplicate_post` and `details.existing_post_id`. The text is compared ignoring spaces at the ends and repeated spaces (case matters). Failed posts do not count, and cancelled ones are deleted. It applies to simulated posts too, so you meet it while testing.

If the person really wants to publish it again, send `"allow_duplicate": true` in the body (in the MCP, `permitir_duplicado: true`).
