Retry requests with idempotency keys
Identify each intended operation and avoid creating duplicate orders after a timeout.
For supported order and artwork creation requests, include a unique Idempotency-Key header. Keep that key with the request and its resulting order or job reference.
Use one key per intended operation
- Generate a unique value, such as a UUID, for the operation.
- Send it in the
Idempotency-Keyheader with your request. - If the same request needs a retry, keep the same key and payload.
- Use a different key for a genuinely new order or artwork job.
Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000Use different keys across endpoints and integrations too. Do not reuse a key for a changed payload and expect validation or a new result. A stored response can be returned instead.
A request timed out
Check whether an order or artwork job was already created. If a retry is appropriate, reuse the original key and request. Creating a fresh key can create another operation.
Avoid concurrent submissions for the same intended operation. Idempotency does not replace checking the resulting order and payment state when an outcome is uncertain.
Retention
Stored keys older than 24 hours are eligible for cleanup. Do not rely on a key to protect a retry indefinitely. Reconcile older or uncertain orders before submitting them again, even with the original key.