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

Мережеві тайм-аути й повторні спроби клієнта — звична річ для multipart-завантажень PDF. Без ключа ідемпотентності другий POST заново запускає те саме об’єднання, OCR чи стиснення, дублюючи завантаження файлу й час обробки. З Idempotency-Key PDF123 може натомість повторити першу успішну відповідь.
Що робить проміжний шар
Проміжний шар сервера в pdfx-server застосовується лише до змінювальних викликів: POST на шляхи під /api/v1/ (зокрема /api/v1/pipeline). GET та інші методи проходять без змін. Якщо в запиті немає заголовка Idempotency-Key (або він порожній після обрізання пробілів), операція виконується звичайно, без пошуку в кеші.
Коли заголовок присутній:
- Сховище формує ключ запису за суб’єктом + ключем. Суб’єкт походить від
X-API-KEY(якkey:…), інакше відAuthorization(якauth:…), інакше береться літералanon. Ці два значення хешуються (SHA-256) у ключ карти; тіло запиту не входить до ключа. - У разі влучання в кеш протягом 24 годин проміжний шар повертає збережені статус, тип вмісту, розташування вмісту й тіло, а також ставить
Idempotency-Replayed: true. - У разі промаху запит виконується далі. Буферизуються й зберігаються лише успішні відповіді (невдалі для повторення не кешуються).
- Тіла відповідей буферизуються до 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-агентів. Сторінки інструментів, як-от Стиснути, лишаються доступними для разових задач у браузері без вигадування ключів.