PPDF123
Product3 menit baca

Idempotency-Key: percobaan ulang yang aman untuk pekerjaan PDF

Kirim Idempotency-Key pada POST di bawah /api/v1/. PDF123 menyimpan respons berhasil 24 jam di memori proses; Idempotency-Replayed: true mencegah pengulangan.

By the PDF123 team Β· Updated 2026-09-30
Idempotency-Key: percobaan ulang yang aman untuk pekerjaan PDF

Timeout jaringan dan percobaan ulang dari klien adalah hal biasa pada unggahan PDF multipart. Tanpa kunci idempotensi, POST kedua menjalankan lagi merge, OCR, atau compress yang sama dari awal, sehingga unggahan dan waktu pemrosesannya terbuang dua kali. Dengan Idempotency-Key, PDF123 bisa memutar ulang respons pertama yang berhasil.

Apa yang dilakukan middleware

Middleware di pdfx-server hanya berlaku untuk panggilan yang mengubah: POST ke jalur di bawah /api/v1/ (termasuk /api/v1/pipeline). GET dan metode lain diteruskan tanpa perubahan. Jika permintaan tidak membawa header Idempotency-Key (atau isinya kosong setelah dipangkas), operasinya berjalan normal tanpa pencarian cache.

Ketika header itu ada:

  1. Penyimpanan memberi kunci entri berdasarkan principal + key. Principal diturunkan dari X-API-KEY (sebagai key:…), jika tidak ada dari Authorization (sebagai auth:…), dan jika keduanya tidak ada dari literal anon. Kedua nilai itu di-hash (SHA-256) menjadi kunci peta; body permintaan bukan bagian dari kunci tersebut.
  2. Pada cache hit dalam 24 jam, middleware mengembalikan status, content type, content disposition, dan body yang tersimpan, lalu menyetel Idempotency-Replayed: true.
  3. Pada miss, permintaan dilanjutkan. Hanya respons yang berhasil yang di-buffer dan disimpan (respons yang tidak berhasil tidak di-cache untuk diputar ulang).
  4. Body respons di-buffer hingga 100 MiB agar pemutaran ulang bisa mengirim ulang byte berkasnya. Body yang tidak bisa di-buffer tidak diam-diam melewati cache: permintaan itu mengembalikan HTTP 500, sehingga respons yang melebihi batas gagal alih-alih lolos tanpa di-cache.

Pekerjaan yang gagal aman dicoba ulang dengan kunci yang sama: karena kegagalannya tidak disimpan, percobaan berikutnya bisa berhasil lalu menjadi hasil yang di-cache. Jangan memakai ulang kunci untuk berkas atau parameter yang berbeda; cache tidak meng-hash body, hanya principal dan key. Dua pemanggil yang tidak berbagi API key maupun Authorization tidak akan bertabrakan secara kebetulan, tetapi pemanggil anonim berbagi principal anon, jadi mereka harus memilih kunci yang berbeda.

Cara mengirimkannya

Pilih string buram yang stabil untuk setiap pekerjaan logis (UUID sudah cukup):

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

Pemanggil anonim maupun pemakai API key sama-sama bisa. Pipeline yang merangkai watermark lalu compress tetap sebaiknya mengirim satu kunci per permintaan HTTP yang ingin Anda deduplikasi, termasuk setiap langkah bila Anda mengirimnya terpisah, atau satu kunci untuk satu panggilan /api/v1/pipeline.

Pekerjaan sekali pakai di browser pada halaman alat (Compress, OCR, …) tidak mengharuskan Anda menciptakan kunci; header ini penting bagi klien yang melakukan percobaan ulang. Skill yang dipublikasikan di /skills/pdf123.md menampilkan Idempotency-Key pada contoh pipeline untuk alasan yang sama.

Pola klien yang berhasil

  • Hasilkan kunci sebelum POST pertama, lalu pakai ulang kunci itu pada percobaan ulang akibat timeout untuk pekerjaan logis yang sama.
  • Setelah berhasil, periksa Idempotency-Replayed: true bila Anda perlu tahu apakah respons ini datang dari cache atau menjalankan operasinya lagi.
  • Ganti kunci ketika berkas, operasi, atau parameternya berubah, meskipun principal-nya tetap sama.
  • Untuk /api/v1/pipeline, satu kunci mencakup seluruh POST pipeline, bukan setiap langkah di dalamnya.

Apa yang bukan pemutaran ulang

Pemutaran ulang bukan antrean pekerjaan yang tahan lama. Penyimpanannya bersifat lokal di proses (HashMap di balik mutex) dengan TTL 24 jam. Setelah kedaluwarsa, atau setelah proses dimulai ulang sehingga peta di memori itu hilang, kunci yang sama akan menjalankan operasinya lagi. Penerapan multi-instance tidak berbagi peta tersebut kecuali Anda menaruh penyimpanan bersama di depannya; middleware hari ini bekerja per proses.

Perlakukan Idempotency-Replayed: true sebagai bukti bahwa respons ini datang dari cache, bukan sebagai catatan permanen. Itu tidak berarti PDF-nya diproses ulang, dan tidak memperpanjang TTL.

Detail permukaan lainnya: Developers dan Dibangun untuk agen AI. Halaman alat seperti Compress tetap tersedia untuk pekerjaan browser sekali pakai tanpa perlu menciptakan kunci.

Open tool
Process in the browser β€” no watermark, files removed after the job.
Open tool