Product3 min di lettura

Idempotency-Key: nuovi tentativi sicuri per le attività PDF

Invia Idempotency-Key nelle POST /api/v1/. PDF123 cachea 24 h le risposte riuscite in memoria del processo; un replay non riesegue e dà Idempotency-Replayed: true.

By the PDF123 team · Updated 2026-09-30
Idempotency-Key: nuovi tentativi sicuri per le attività PDF

Timeout di rete e nuovi tentativi del client sono normali con i caricamenti PDF multipart. Senza una chiave di idempotenza, una seconda POST riesegue da capo lo stesso merge, la stessa OCR o la stessa compressione, duplicando il caricamento e il tempo di elaborazione. Con Idempotency-Key, PDF123 può invece riprodurre la prima risposta andata a buon fine.

Cosa fa il middleware

Il middleware del server in pdfx-server si applica solo alle chiamate che modificano lo stato: POST verso percorsi sotto /api/v1/ (compreso /api/v1/pipeline). GET e gli altri metodi passano invariati. Se la richiesta non ha l'intestazione Idempotency-Key (o è vuota dopo il trim), l'operazione gira normalmente senza consultare la cache.

Quando l'intestazione è presente:

  1. L'archivio indicizza la voce per principal + chiave. Il principal deriva da X-API-KEY (come key:…), altrimenti da Authorization (come auth:…), altrimenti dal valore letterale anon. Quei due valori vengono trasformati con hash (SHA-256) nella chiave della mappa; il corpo della richiesta non fa parte della chiave.
  2. In caso di riscontro in cache entro 24 ore, il middleware restituisce status, tipo di contenuto, disposizione del contenuto e corpo memorizzati, e imposta Idempotency-Replayed: true.
  3. In caso di mancato riscontro, la richiesta prosegue. Solo le risposte riuscite vengono bufferizzate e memorizzate (le risposte non riuscite non finiscono in cache per la ripetizione).
  4. I corpi delle risposte vengono bufferizzati fino a 100 MiB, così una ripetizione può reinviare i byte del file. Un corpo che non può essere bufferizzato non salta la cache in silenzio: quella richiesta restituisce HTTP 500, quindi una risposta oltre il limite fallisce invece di passare senza cache.

Le attività fallite si possono ritentare in sicurezza con la stessa chiave: poiché i fallimenti non vengono memorizzati, il tentativo successivo può riuscire e diventare poi il risultato in cache. Non riutilizzare una chiave per un file o parametri diversi: la cache non calcola l'hash del corpo, solo del principal e della chiave. Due chiamanti che non condividono né API key né Authorization non possono collidere per caso; i chiamanti anonimi condividono il principal anon, quindi devono scegliere chiavi distinte.

Come inviarla

Scegli una stringa opaca e stabile per ogni attività logica (un UUID va bene):

curl -X POST "https://pdf123.xyz/api/v1/misc/compress-pdf" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -F "[email protected]"

Funziona sia per i chiamanti anonimi sia per quelli con API key. Le pipeline che concatenano filigrana e poi compressione dovrebbero comunque inviare una chiave per ogni richiesta HTTP che vuoi deduplicare, compreso ogni passaggio se li invii separatamente, oppure una sola chiave per una singola chiamata a /api/v1/pipeline.

Le attività occasionali nel browser sulle pagine degli strumenti (Comprimi, OCR e così via) non richiedono di inventare una chiave; l'intestazione conta per i client che ritentano. La skill pubblicata su /skills/pdf123.md mostra un Idempotency-Key su un esempio di pipeline per lo stesso motivo.

Schemi di client che funzionano

  • Genera la chiave prima della prima POST; riutilizzala nei nuovi tentativi dopo un timeout per quella stessa attività logica.
  • In caso di successo, controlla Idempotency-Replayed: true se ti serve sapere se la risposta proviene dalla cache o se l'operazione è stata rieseguita.
  • Cambia la chiave quando cambiano il file, l'operazione o i parametri, anche se il principal resta lo stesso.
  • Per /api/v1/pipeline, una sola chiave copre l'intera POST della pipeline, non ogni passaggio interno.

Cosa non è la ripetizione

La ripetizione non è una coda di lavoro durevole. L'archivio è locale al processo (HashMap dietro un mutex) con un TTL di 24 ore. Dopo la scadenza, o dopo un riavvio del processo che azzera la mappa in memoria, la stessa chiave riesegue l'operazione. I deployment con più istanze non condividono quella mappa, a meno di mettere davanti un archivio condiviso: il middleware attuale è per processo.

Considera Idempotency-Replayed: true come prova che la risposta proviene dalla cache, non come un registro permanente. Non significa che il PDF sia stato rielaborato e non prolunga il TTL.

Per maggiori dettagli sull'API: Developers e Costruito per gli agenti AI. Le pagine degli strumenti come Comprimi restano disponibili per attività occasionali nel browser, senza inventare chiavi.

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