Product3 мин чтения

Idempotency-Key: безопасные повторные попытки для PDF-задач

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

By the PDF123 team · Updated 2026-09-30
Idempotency-Key: безопасные повторные попытки для PDF-задач

Сетевые тайм-ауты и повторы на стороне клиента — обычное дело для multipart-загрузок PDF. Без ключа идемпотентности второй POST заново запускает то же слияние, OCR или сжатие с нуля, дублируя загрузку и время обработки. С Idempotency-Key PDF123 может вместо этого воспроизвести первый успешный ответ.

Что делает middleware

Серверное middleware в pdfx-server применяется только к изменяющим вызовам: POST по путям под /api/v1/ (включая /api/v1/pipeline). GET и другие методы проходят без изменений. Если в запросе нет заголовка Idempotency-Key (или он пуст после обрезки пробелов), операция выполняется как обычно, без обращения к кэшу.

Когда заголовок присутствует:

  1. Хранилище строит ключ записи по principal + key. Principal выводится из X-API-KEY (как key:…), иначе из Authorization (как auth:…), иначе берётся литерал anon. Эти два значения хешируются (SHA-256) в ключ карты; тело запроса не входит в ключ.
  2. При попадании в кэш в течение 24 часов middleware возвращает сохранённые статус, тип содержимого, disposition содержимого и тело, а также ставит Idempotency-Replayed: true.
  3. При промахе запрос выполняется. Буферизуются и сохраняются только успешные ответы (неуспешные не кэшируются для воспроизведения).
  4. Тела ответов буферизуются до 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-агентов. Страницы инструментов вроде Сжатия остаются доступными для разовых задач в браузере без изобретения ключей.

Open tool
Process in the browser — no watermark, files removed after the job.
Open tool