This post was drafted with AI assistance and reviewed by the PerfectVector team.
When an AI agent calls a paid API, it will retry. Timeouts, dropped connections and restarted tool loops all produce duplicate requests, and a duplicate that charges twice is the bug people remember. This post is about the contract: what an API should promise on a retry, a conflict and a failure. The examples are real responses from the PerfectVector Developer API, recorded with a test key on 2026-11-13. (For client code that uses these rules, see the Python post earlier this week.)
The rule: one key, one conversion. POST /v1/vectorizations takes an Idempotency-Key (8–128 characters: letters, digits, -, _). The same key with the same image bytes returns the original conversion in its current state:
POST /v1/vectorizations Idempotency-Key: devto-wed-001 (256×256 PNG) → 201 x-credits-charged: 0 x-credits-would-charge: 1 Same key, same image, again → 201 idempotent-replayed: true x-credits-charged: 0 same vec_ id Reusing a key for a different request is refused. We sent the same key with a different, valid 300×200 image:
→ 409 idempotency_conflict "This Idempotency-Key was used for a different request (another image or other options). Send a new key." Nothing is created or charged. The docs say "same request" means the same image bytes and options; the file name and the Prefer and Accept headers don't count.
What an error does to a key. The docs say a request refused with a 400, 402, 413, 415, 422, 429 or 503 doesn't tie the key to anything: fix the request and retry with the same key. In one recorded case we sent the already-used key with a 64×64 image and got 422 invalid_image, not a 409, and a fresh key with the same small image got the same 422. We can't say from that one case what the server's full order of checks is. The practical rule is the documented one: a rejected request leaves the key unused, but a key that already produced a conversion stays bound to that conversion's image.
Failure is free. A failed conversion is not an HTTP error. It answers 201 with "status": "failed" and charges nothing, and a replayed failure stays failed, so a retry needs a new key. A live key is charged 1 credit only when a conversion succeeds. Status checks and repeat downloads cost nothing.
| What happened | Retry with | Charge for that attempt |
|---|---|---|
| Timeout or dropped connection | the same key | at most once, on success |
409 idempotency_conflict | a new key | none |
422, 413, 415, 400 | the same key, after fixing the request | none |
201 with status: failed | a new key | none |
429 / 503 | the same key, after Retry-After | none |
500 | the same key | at most once, on success |
The "charge" column is about the attempt that failed or was refused. A corrected or new-key request that succeeds on a live key costs 1 credit, like any conversion.
What to copy into your own API
- Make the key part of the contract and say which parts of a request count as "the same".
- Return the original conversion in its current state on a replay and flag ordinary replays with a header. Document the exceptions: two identical requests that arrive at the same time get the same conversion, and the second answer may not carry the replay header.
- Say what an error does to the key.
- Make "failed" a normal response with a status field, and don't charge for it.
- Publish a retry table that makes each condition and its next action explicit.
Keys live for 24 hours. Without the header, the API still works, but every request is a new conversion, so a retry after a timeout can convert, and charge, the same image twice.
Docs: Idempotency.
We build PerfectVector, an image-to-vector tool.