Idempotency-Key: безопасные повторные попытки для PDF-задач
Отправляйте Idempotency-Key при POST под /api/v1/. PDF123 кэширует успешные ответы на 24 часа в памяти процесса и ставит Idempotency-Replayed: true вместо повтора.

Сетевые тайм-ауты и повторы на стороне клиента — обычное дело для multipart-загрузок PDF. Без ключа идемпотентности второй POST заново запускает то же слияние, OCR или сжатие с нуля, дублируя загрузку и время обработки. С Idempotency-Key PDF123 может вместо этого воспроизвести первый успешный ответ.
Что делает middleware
Серверное middleware в pdfx-server применяется только к изменяющим вызовам: POST по путям под /api/v1/ (включая /api/v1/pipeline). GET и другие методы проходят без изменений. Если в запросе нет заголовка Idempotency-Key (или он пуст после обрезки пробелов), операция выполняется как обычно, без обращения к кэшу.
Когда заголовок присутствует:
- Хранилище строит ключ записи по principal + key. Principal выводится из
X-API-KEY(какkey:…), иначе изAuthorization(какauth:…), иначе берётся литералanon. Эти два значения хешируются (SHA-256) в ключ карты; тело запроса не входит в ключ. - При попадании в кэш в течение 24 часов middleware возвращает сохранённые статус, тип содержимого, disposition содержимого и тело, а также ставит
Idempotency-Replayed: true. - При промахе запрос выполняется. Буферизуются и сохраняются только успешные ответы (неуспешные не кэшируются для воспроизведения).
- Тела ответов буферизуются до 100 MiB, чтобы воспроизведение могло переслать байты файла. Тело, которое не удаётся буферизовать, не пропускает кэш молча: такой запрос возвращает HTTP 500, поэтому ответ сверх лимита завершается сбоем, а не проходит без кэширования.
Неудачные задачи безопасно повторять с тем же ключом: поскольку сбои не сохраняются, следующая попытка может удаться и затем стать кэшированным результатом. Не используйте один ключ для другого файла или параметров; кэш не хеширует тело, только principal и ключ. Два вызывающих, не разделяющих ни API-ключ, ни Authorization, не могут столкнуться случайно: анонимные вызывающие делят principal anon, поэтому им нужно выбирать разные ключи.
Как его отправлять
Выберите стабильную непрозрачную строку для каждой логической задачи (UUID подойдёт):
curl -X POST "https://pdf123.xyz/api/v1/misc/compress-pdf" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
-F "[email protected]"
Работают и анонимные вызывающие, и вызывающие с API-ключом. Конвейеры, соединяющие водяной знак, а затем сжатие, всё равно должны отправлять один ключ на каждый HTTP-запрос, который вы хотите дедуплицировать, — включая каждый шаг, если вы отправляете их отдельно, или один ключ на единственный вызов /api/v1/pipeline.
Разовые задачи в браузере на страницах инструментов (Сжатие, OCR, …) не требуют изобретать ключ; заголовок важен для клиентов, которые повторяют попытки. Опубликованный skill по адресу /skills/pdf123.md показывает Idempotency-Key в примере pipeline по той же причине.
Клиентские шаблоны, которые работают
- Сгенерируйте ключ до первого POST; переиспользуйте его при повторах по тайм-ауту для той же логической задачи.
- При успехе проверьте
Idempotency-Replayed: true, если нужно знать, пришёл ли этот ответ из кэша или операция выполнилась заново. - Меняйте ключ, когда меняется файл, операция или параметры, даже если principal остаётся тем же.
- Для
/api/v1/pipelineодин ключ покрывает весь POST конвейера, а не каждый внутренний шаг.
Чем воспроизведение не является
Воспроизведение — не долговечная очередь задач. Хранилище локально для процесса (HashMap под мьютексом) с TTL 24 часа. После истечения срока или после перезапуска процесса, сбрасывающего карту в памяти, тот же ключ запустит операцию снова. Развёртывания с несколькими экземплярами не разделяют эту карту, если вы не поставите перед ними общее хранилище; сегодняшнее middleware работает на процесс.
Считайте Idempotency-Replayed: true доказательством того, что ответ пришёл из кэша, а не постоянным реестром. Это не значит, что PDF был обработан заново, и не продлевает TTL.
Больше деталей поверхности: Разработчикам и Создан для AI-агентов. Страницы инструментов вроде Сжатия остаются доступными для разовых задач в браузере без изобретения ключей.