# Safe retries with Idempotency-Key

Retry POST /v1/vectorizations without converting or paying twice.

> **Coming soon:** The Developer API opens soon. You can read the docs now; API keys arrive when it opens.

Networks fail. A request can succeed on our side while your client sees a timeout. Send an
`Idempotency-Key` with every `POST /v1/vectorizations`, and a retry returns the same conversion
instead of starting a new one.

```bash
curl https://api.perfectvector.com/v1/vectorizations \
  -H "Authorization: Bearer $PERFECTVECTOR_API_KEY" \
  -H "Idempotency-Key: order-1042-logo" \
  -F image=@logo.png
```

## The rules

| Rule | Detail |
|---|---|
| Format | 8 to 128 characters: letters, digits, `-` and `_`. Anything else answers `400 invalid_request`. |
| Choose it from your own data | For example your order or file ID: `order-1042-logo`. A random UUID works too, if you store it before you send the request. |
| Lifetime | 24 hours from the first request. After that, the same key starts a new conversion. |
| Scope | Your account and the key's mode. All keys of an account share the same keys; test and live are separate. |
| Same request | The same image bytes and the same `options`. The file name and the `Prefer` and `Accept` headers do not count. |
| Endpoints | Only `POST /v1/vectorizations`. The other endpoints are safe to repeat as they are. |

## What a retry returns

- **Same key, same request:** the original conversion **in its current state**, with the header
  `Idempotent-Replayed: true` and `X-Credits-Charged: 0`. It is never charged twice. The status code
  follows the usual rule: `201` when it has finished, `202` while it is running.
- **Same key, a different image or other options:** `409 idempotency_conflict`. Nothing is created
  or charged. Use a new key for a new request.
- **Two identical requests at the same time:** they are handled one after the other, and both get
  the same conversion, charged once. The second answer may not carry `Idempotent-Replayed`.

A replayed failure stays failed. To try a failed conversion again, send it with a **new** key.

## When a key is not used up

If the API refuses a request with an error (for example `400`, `402`, `413`, `415`, `422`, `429` or
`503`), the key is not tied to anything: fix the problem and retry with the same key. After a `500`
or a dropped connection, retry with the same key: you get the conversion if it was accepted, or a
fresh start if it was not.

## Without the header

The API still works, but every request is a new conversion. A retry after a timeout can then convert,
and charge, the same image twice.

[Site index](https://perfectvector.com/llms.txt) — available pages and descriptions.