> ## Documentation Index
> Fetch the complete documentation index at: https://docs.printools.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Writing safely

> Retry writes with idempotency keys and respect request limits.

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.

```bash theme={"dark"}
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](/api/reference/post_v1_quotes).

| Header                 | Behaviour                                                                                     |
| ---------------------- | --------------------------------------------------------------------------------------------- |
| `Idempotency-Key`      | A client-generated string of 1 to 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](/api/reference/get_v1_reference_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.