Writing safely - PRINTOOLS Docs

Use an Idempotency-Key when retrying writes. The header is optional in the published contract, but sending it helps prevent a retry from repeating the same logical operation.

One key per operation

Generate a unique key for a new logical write. If that request times out, retry with the same key and the same request.

curl -X POST 'https://api.printools.io/v1/quotes' \
  -H "X-API-Key: ${PRINTOOLS_API_KEY}" \
  -H "Idempotency-Key: ${PRINTOOLS_IDEMPOTENCY_KEY}" \
  -H 'Content-Type: application/json' \
  --data-binary @quote.json

Build quote.json using the request schema on Create a quote.

Header	Behaviour
`Idempotency-Key`	A client-generated string of 1–200 characters. Reuse it only for the same logical request.
`Idempotency-Replayed`	`true` on a replayed result.

Conflicts and uncertain results

Reusing a key with a different request returns 409. An in-flight idempotent request can also return a conflict. If the outcome of an earlier attempt is uncertain, check the affected resource before starting another write with a new key. A new key represents a new operation.

Request and batch limits

Read Current limits before a large import. An oversized JSON request returns 413. Bulk endpoints have their own request schemas. Use the documented target, filter, or item fields for that operation, and split work into batches within the published limits.