API v1 preview
Idempotent requests
Retry the same operation without creating duplicates.
Protect a request from duplicates
Create a unique Idempotency-Key before the first request and save it with the body. Reuse both after a timeout or lost response. Do not generate a new key inside a retry loop.
Retry header
http
Idempotency-Key: 6e94ce83-0244-4d6c-93ba-f8b2687311d6| Endpoint | Key |
|---|---|
| Create an order / Pay an order | Required |
| Create a file / Create a model / Replace a model file / Calculate prices / Create a quote / Cancel an order | Optional; recommended |
| GET | Not needed |
| Update a model | No key replay; use If-Match and reconcile with GET after a lost response. |
| Delete a model | Retrieve the model after a lost response; repeated calls may return 404. |
Key lifetime and scope
- Use 1–255 visible ASCII characters; a random UUID is suitable.
- Every public POST accepts a key; order creation and payments require one. Keys are scoped to account, HTTP method and path for 24 hours from first use.
- The same parsed JSON body replays saved response values with
Idempotent-Replayed: true. Object key order and whitespace can differ. - A changed body returns
409 idempotency_key_reused. Successful replays do not consume another creation quota slot. - Without a key, or after its retention window, a retry may create a duplicate. Reconcile the resource before starting a new operation.
What a replay returns
| Resource | Behavior |
|---|---|
| File | Original instructions and expiry, even after linking. Replay does not renew upload permission. |
| Model | Original creation snapshot, even after deletion. GET returns current availability and results. |
| Model file replacement | Original replacement snapshot. No duplicate file revision, even after another edit. |
| Quote | Original creation snapshot, including its original status. GET reports current expiry. No new rates or extended expiry. Failed admitted attempts also bind the key to the body. |
| Order | Original order snapshot, even after cancellation. GET returns current state. |
| Payment | Original payment action, which may include an expired URL. GET the order for current state. |
| Cancel order / Calculate prices | Original successful snapshot. GET the order for later refund progress; calculate with a new key for fresh prices. |
A concurrent request with the same key returns 409 idempotency_request_in_progress and Retry-After. Wait that many seconds, then retry the same key and body. Dependency failures return 503 with Retry-After; unsuccessful attempts can be retried and keep their body binding. Never create another order to recover an uncertain payment.
API v1 preview