PPDF123
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 може натомість повторити першу успішну відповідь.

Що робить проміжний шар

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

Коли заголовок присутній:

  1. Сховище формує ключ запису за суб’єктом + ключем. Суб’єкт походить від X-API-KEY (як key:…), інакше від Authorization (як auth:…), інакше береться літерал anon. Ці два значення хешуються (SHA-256) у ключ карти; тіло запиту не входить до ключа.
  2. У разі влучання в кеш протягом 24 годин проміжний шар повертає збережені статус, тип вмісту, розташування вмісту й тіло, а також ставить Idempotency-Replayed: true.
  3. У разі промаху запит виконується далі. Буферизуються й зберігаються лише успішні відповіді (невдалі для повторення не кешуються).
  4. Тіла відповідей буферизуються до 100 МіБ, щоб повторення могло надіслати байти файлу знову. Тіло, яке не вдалося буферизувати, не пропускає кеш тихо: такий запит повертає HTTP 500, тож відповідь понад ліміт зазнає збою, а не проходить без кешування.

Невдалі завдання безпечно повторювати з тим самим ключем: оскільки збої не зберігаються, наступна спроба може вдатися й тоді стати кешованим результатом. Не використовуйте ключ повторно для іншого файлу чи параметрів; кеш не хешує тіло, лише суб’єкта й ключ. Два клієнти, які не мають спільного ні ключа API, ні Authorization, не можуть зіткнутися випадково — анонімні клієнти поділяють суб’єкт 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, …) не вимагають вигадувати ключ; заголовок важливий для клієнтів, які повторюють спроби. Опублікована навичка за адресою /skills/pdf123.md показує Idempotency-Key на прикладі конвеєра саме з цієї причини.

Робочі шаблони клієнтів

  • Генеруйте ключ перед першим POST; використовуйте його повторно при тайм-аутах для того самого логічного завдання.
  • У разі успіху перевіряйте Idempotency-Replayed: true, якщо потрібно знати, чи ця відповідь прийшла з кешу, чи операція виконалася знову.
  • Змінюйте ключ, коли змінюється файл, операція чи параметри — навіть якщо суб’єкт лишається тим самим.
  • Для /api/v1/pipeline один ключ покриває весь POST конвеєра, а не кожен внутрішній крок.

Чим повторення не є

Повторення — не довговічна черга завдань. Сховище локальне для процесу (HashMap за м’ютексом) із TTL 24 години. Після закінчення строку або після перезапуску процесу, який відкидає карту в пам’яті, той самий ключ запускає операцію знову. Розгортання з кількома екземплярами не поділяють цю карту, якщо не поставити перед ними спільне сховище — сьогоднішній проміжний шар працює в межах процесу.

Сприймайте Idempotency-Replayed: true як доказ того, що ця відповідь прийшла з кешу, а не як постійний реєстр. Це не означає, що PDF обробили знову, і не подовжує TTL.

Докладніше про поверхню: Розробникам і Зроблено для AI-агентів. Сторінки інструментів, як-от Стиснути, лишаються доступними для разових задач у браузері без вигадування ключів.

Open tool
Process in the browser — no watermark, files removed after the job.
Open tool
Read next
Редагування тексту в PDF онлайн: виправити файл без першоджерела
Клацніть рядок тексту в PDF, змініть його й завантажте результат. Нічого не вивантажується на сервер, входити в обліковий запис не потрібно. Редагувати можна лише рядки тексту, які вже є у файлі.
Від набору сканів до тексту: спершу OCR, потім стиснення PDF, який ви лишаєте
Набір сканів потребує двох кроків: OCR на PDF123 повертає текст Markdown, а Compress зменшує вихідний PDF перестисненням потоків. Порядок і виводи різні.
Що таке PDF123: безкоштовний набір інструментів для PDF, який можна розмістити в себе
PDF123 — це безкоштовний набір інструментів для PDF у браузері: усі 56 інструментів, від об’єднання й стиснення до OCR і шифрування, працюють без облікового запису. Ті самі операції доступні через REST, MCP і CLI pdfx, або ж стек можна розгорнути на власному хостингу й тримати файли у своїй мережі.