Skip to article
PerfectVectorDocs
Open PerfectVector
Browse docsIdempotency
APIGuides

Safe retries with Idempotency-Key

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

3 min read
Coming soon

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

On this page

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.

Example request
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

RuleDetail
Format8 to 128 characters: letters, digits, - and _. Anything else answers 400 invalid_request.
Choose it from your own dataFor example your order or file ID: order-1042-logo. A random UUID works too, if you store it before you send the request.
Lifetime24 hours from the first request. After that, the same key starts a new conversion.
ScopeYour account and the key's mode. All keys of an account share the same keys; test and live are separate.
Same requestThe same image bytes and the same options. The file name and the Prefer and Accept headers do not count.
EndpointsOnly 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.

Reviewed
Safe retries with Idempotency-Key · PerfectVector Docs