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 (или тя е празна след премахване на интервали), операцията се изпълнява нормално, без търсене в кеша.
Когато заглавката е налице:
- Хранилището ключва записа по principal + ключ. Principal се извежда от
X-API-KEY(катоkey:…), иначе отAuthorization(катоauth:…), иначе от буквалнотоanon. Тези две стойности се хешират (SHA-256) в ключа на картата; тялото на заявката не е част от ключа. - При попадение в кеша в рамките на 24 часа междинният слой връща запазените статус, тип на съдържанието, разположение на съдържанието и тяло и задава
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.
Еднократните задачи в браузъра на страниците с инструменти (Compress, OCR, …) не изискват да измисляте ключ; заглавката има значение за клиентите, които повтарят. Публикуваният skill на /skills/pdf123.md показва Idempotency-Key в пример за pipeline по същата причина.
Клиентски модели, които работят
- Генерирайте ключа преди първия POST; използвайте го повторно при повторни опити след прекъсване за същата логическа задача.
- При успех проверете
Idempotency-Replayed: true, ако трябва да знаете дали този отговор е дошъл от кеша, или операцията е изпълнена отново. - Сменете ключа, когато файлът, операцията или параметрите се променят, дори ако principal остава същият.
- За
/api/v1/pipelineедин ключ покрива цялата POST заявка на pipeline, а не всяка вътрешна стъпка.
Какво не е повторението
Повторението не е трайна опашка от задачи. Хранилището е локално за процеса (HashMap зад mutex) с TTL от 24 часа. След изтичане или след рестарт на процеса, който изхвърля картата в паметта, същият ключ изпълнява операцията отново. Внедряванията с няколко инстанции не споделят тази карта, освен ако не поставите споделено хранилище отпред; днешният междинен слой е за отделен процес.
Третирайте Idempotency-Replayed: true като доказателство, че този отговор е дошъл от кеша, а не като постоянен регистър. Той не означава, че PDF е обработен отново, и не удължава TTL.
Повече подробности за повърхността: Developers и Създаден за AI агенти. Страниците с инструменти като Compress остават достъпни за еднократни задачи в браузъра без измисляне на ключове.