Idempotency-Key: säkra återförsök för PDF-jobb
Idempotency-Key på POST-jobb under /api/v1/: PDF123 cachar lyckade svar 24 h i processlokalt minne och sätter Idempotency-Replayed: true i stället för omkörning.

Nätverkstimeouts och återförsök från klienten är normala vid uppladdning av PDF:er som multipart. Utan en idempotensnyckel kör en andra POST samma sammanslagning, OCR eller komprimering från början igen, vilket duplicerar både uppladdningen och bearbetningstiden. Med Idempotency-Key kan PDF123 i stället spela upp det första lyckade svaret.
Vad den mellanliggande programvaran gör
Serverns mellanliggande programvara i pdfx-server gäller bara förändrande anrop: POST till vägar under /api/v1/ (inklusive /api/v1/pipeline). GET och andra metoder passerar oförändrade. Saknar begäran huvudet Idempotency-Key (eller är det tomt efter borttagning av blanksteg) körs operationen normalt utan uppslag i cachen.
När huvudet finns:
- Lagret nycklar posten med huvudman + nyckel. Huvudmannen härleds från
X-API-KEY(somkey:…), annars frånAuthorization(somauth:…), annars från den bokstavliga strängenanon. De två värdena hashas (SHA-256) till nyckeln i mappen; själva begärandekroppen är inte en del av nyckeln. - Vid en träff i cachen inom 24 timmar returnerar programvaran den lagrade statuskoden, innehållstypen,
Content-Dispositionoch kroppen, och sätterIdempotency-Replayed: true. - Vid en miss fortsätter begäran. Endast lyckade svar buffras och lagras (misslyckade svar cachas inte för uppspelning).
- Svarskroppar buffras upp till 100 MiB så att en uppspelning kan skicka filbyten igen. En kropp som inte kan buffras hoppar inte tyst över cachen: den begäran returnerar HTTP 500, så ett svar över gränsen misslyckas i stället för att passera ocachat.
Misslyckade jobb är säkra att försöka igen med samma nyckel: eftersom misslyckanden inte lagras kan nästa försök lyckas och sedan bli det cachade resultatet. Återanvänd inte en nyckel för en annan fil eller andra parametrar; cachen hashar inte kroppen, bara huvudmannen och nyckeln. Två anropare som varken delar API-nyckel eller Authorization kan inte kollidera av misstag, men anonyma anropare delar huvudmannen anon och måste därför välja olika nycklar.
Hur du skickar den
Välj en stabil, ogenomskinlig sträng per logiskt jobb (ett UUID fungerar):
curl -X POST "https://pdf123.xyz/api/v1/misc/compress-pdf" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
-F "[email protected]"
Både anonyma anropare och anropare med API-nyckel fungerar. Kedjor som först vattenstämplar och sedan komprimerar bör ändå skicka en nyckel per HTTP-begäran som du vill deduplicera, inklusive varje steg om du skickar dem separat, eller en nyckel för ett enda anrop till /api/v1/pipeline.
Engångsjobb i webbläsaren på verktygssidor (Komprimera PDF, OCR med flera) kräver inte att du hittar på en nyckel; huvudet spelar roll för klienter som gör återförsök. Den publicerade skillen på /skills/pdf123.md visar en Idempotency-Key i ett pipeline-exempel av samma skäl.
Klientmönster som fungerar
- Generera nyckeln före den första POST-begäran och återanvänd den vid återförsök efter en timeout för samma logiska jobb.
- Vid framgång, kontrollera
Idempotency-Replayed: trueom du behöver veta om svaret kom från cachen eller om operationen kördes igen. - Byt nyckel när filen, operationen eller parametrarna ändras, även om huvudmannen är densamma.
- För
/api/v1/pipelinetäcker en nyckel hela pipeline-POSTen, inte varje enskilt steg.
Vad uppspelningen inte är
Uppspelningen är ingen varaktig jobbkö. Lagret är lokalt för processen (en HashMap bakom ett lås) med en TTL på 24 timmar. Efter att TTL:n gått ut, eller efter en omstart av processen som tömmer mappen i minnet, kör samma nyckel operationen igen. Installationer med flera instanser delar inte mappen om du inte sätter ett delat lager framför; dagens programvara är per process.
Behandla Idempotency-Replayed: true som ett bevis på att svaret kom från cachen, inte som en permanent liggare. Det betyder varken att PDF:en bearbetades om eller att TTL:n förlängs.
Mer information om ytan: Utvecklare och Byggd för AI-agenter. Verktygssidor som Komprimera PDF finns kvar för engångsjobb i webbläsaren utan att du behöver hitta på nycklar.