Product3 min. lezen

Idempotency-Key: veilige nieuwe pogingen voor PDF-taken

Idempotency-Key op POST-taken onder /api/v1/: PDF123 bewaart successen 24 uur in proceslokaal geheugen en zet Idempotency-Replayed: true in plaats van dubbel werk.

By the PDF123 team · Updated 2026-09-30
Idempotency-Key: veilige nieuwe pogingen voor PDF-taken

Netwerktime-outs en nieuwe pogingen van clients zijn normaal bij multipart-uploads van PDF's. Zonder idempotency-sleutel voert een tweede POST dezelfde merge, OCR of compressie opnieuw vanaf nul uit, wat de upload en de verwerkingstijd dupliceert. Met Idempotency-Key kan PDF123 in plaats daarvan het eerste geslaagde antwoord opnieuw afspelen.

Wat de middleware doet

De servermiddleware in pdfx-server geldt alleen voor wijzigende aanroepen: POST naar paden onder /api/v1/ (inclusief /api/v1/pipeline). GET en andere methoden gaan ongewijzigd door. Heeft het verzoek geen header Idempotency-Key (of is die na het trimmen leeg), dan draait de bewerking normaal, zonder opzoeken in de cache.

Is de header wel aanwezig:

  1. De opslag gebruikt als sleutel van de vermelding principal + key. De principal komt uit X-API-KEY (als key:…), anders uit Authorization (als auth:…), anders is die letterlijk anon. Die twee waarden worden met SHA-256 gehasht tot de sleutel in de map; de body van het verzoek maakt geen deel uit van de sleutel.
  2. Bij een treffer in de cache binnen 24 uur geeft de middleware de opgeslagen status, het contenttype, de content-disposition en de body terug, en zet Idempotency-Replayed: true.
  3. Bij geen treffer gaat het verzoek verder. Alleen geslaagde antwoorden worden gebufferd en opgeslagen (antwoorden die niet geslaagd zijn, worden niet bewaard voor herhaling).
  4. Antwoordlichamen worden tot 100 MiB gebufferd, zodat een herhaling de bytes van het bestand opnieuw kan sturen. Een antwoordlichaam dat niet gebufferd kan worden, slaat de cache niet stil over: dat verzoek geeft HTTP 500, dus een te groot antwoord mislukt in plaats van ongecacheerd door te gaan.

Mislukte taken kunt u veilig opnieuw proberen met dezelfde sleutel: omdat mislukkingen niet worden opgeslagen, kan de volgende poging slagen en dan het bewaarde resultaat worden. Hergebruik een sleutel niet voor een ander bestand of andere parameters; de cache hasht de body niet, alleen de principal en de sleutel. Twee aanroepers die noch hun API-sleutel noch hun Authorization delen, kunnen niet per ongeluk botsen; anonieme aanroepers delen de principal anon en moeten dus verschillende sleutels kiezen.

Hoe u de header verstuurt

Kies per logische taak een stabiele, willekeurige tekenreeks (een UUID is prima):

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

Anonieme aanroepers en aanroepers met een API-sleutel werken beide. Pijplijnen die eerst watermerken en dan comprimeren, sturen nog steeds één sleutel per HTTP-verzoek dat u wilt dedupliceren: voor elke stap als u ze apart POST, of één sleutel voor één aanroep van /api/v1/pipeline.

Eenmalige taken in de browser op toolpagina's (Compress, OCR, …) vragen niet dat u een sleutel verzint; de header is van belang voor clients die het opnieuw proberen. De gepubliceerde skill op /skills/pdf123.md toont om dezelfde reden een Idempotency-Key bij een pipelinevoorbeeld.

Clientpatronen die werken

  • Genereer de sleutel voordat u de eerste POST doet; hergebruik hem bij nieuwe pogingen na een time-out voor diezelfde logische taak.
  • Controleer bij succes op Idempotency-Replayed: true als u wilt weten of dit antwoord uit de cache kwam of dat de bewerking opnieuw is uitgevoerd.
  • Wijzig de sleutel wanneer het bestand, de bewerking of de parameters veranderen, ook als de principal hetzelfde blijft.
  • Voor /api/v1/pipeline dekt één sleutel de hele POST naar de pijplijn, niet elke afzonderlijke stap daarbinnen.

Wat herhaling niet is

Herhaling is geen duurzame wachtrij voor taken. De opslag is proceslokaal (HashMap achter een mutex) met een TTL van 24 uur. Na het aflopen van die termijn, of na een herstart van het proces waarbij de map in het geheugen verdwijnt, voert dezelfde sleutel de bewerking opnieuw uit. Uitrollen met meerdere exemplaren delen die map niet, tenzij u er een gedeelde opslag voor zet; de middleware van vandaag werkt per proces.

Zie Idempotency-Replayed: true als bewijs dat dit antwoord uit de cache kwam, niet als een permanent grootboek. Het betekent niet dat de PDF opnieuw is verwerkt, en het verlengt de TTL niet.

Meer details over het oppervlak: Developers en Built for AI agents. Toolpagina's zoals Compress blijven beschikbaar voor eenmalige taken in de browser, zonder dat u sleutels hoeft te verzinnen.

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