Idempotency-Key:PDF 工作的安全重試
/api/v1/ 下的 POST 帶上 Idempotency-Key;成功回應存於行程內記憶體 24 小時,重啟即丟,命中設 Idempotency-Replayed,不重跑。

multipart PDF 上傳遇到網路逾時與用戶端重試,是家常便飯。沒有冪等鍵時,第二次 POST 可能把同一份合併、OCR 或壓縮又跑一遍,白白多傳一次、多算一遍。帶上 Idempotency-Key,PDF123 就能把第一次成功的回應重放給你。
中介層做了什麼
pdfx-server 裡的伺服器中介層只套用在變更型呼叫:對 /api/v1/ 下路徑的 POST,其中包含 /api/v1/pipeline。GET 與其他方法原樣通過。如果請求沒有 Idempotency-Key 標頭,或者 trim 之後是空的,op 就正常執行,不做快取查找。
標頭存在時:
- 儲存項目以主體 + 金鑰為鍵。主體取自
X-API-KEY(記為key:…),否則取Authorization(記為auth:…),都沒有就用字面值anon。這兩個值經 SHA-256 雜湊成對映鍵;請求本體不參與其中。 - 24 小時內命中快取時,中介層會回傳已儲存的狀態碼、內容類型、內容處置與本體,並設定
Idempotency-Replayed: true。 - 未命中就繼續執行。只有成功的回應會被緩衝並儲存(非成功的回應不會被快取供重放)。
- 回應本體最多緩衝 100 MiB,重放時才能把檔案位元組重新送出去。緩衝不了的本體不會悄悄跳過快取:該請求會回傳 HTTP 500,所以超過上限的回應會失敗,而不是不經快取直接放行。
失敗的工作可以用同一個金鑰安全重試:失敗不會入庫,下一次嘗試成功之後就成為快取結果。不要把同一個金鑰用到不同的檔案或參數上;快取不雜湊本體,只雜湊主體與金鑰。既不共享 API Key 也不共享 Authorization 的兩個呼叫方不會意外撞鍵;匿名呼叫方共享 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 Key 呼叫方都能用。先浮水印再壓縮的管線,仍然應該為每一個想去重的 HTTP 請求送一把金鑰:分步驟 POST 就每步一把,單次 /api/v1/pipeline 呼叫則一把金鑰覆蓋整條管線。
工具頁上的瀏覽器一次性工作(壓縮 PDF、OCR 等)不需要你發明金鑰,這個標頭是給會重試的用戶端用的。發布在 /skills/pdf123.md 的 skill 在 pipeline 範例裡帶上 Idempotency-Key,也是同一個道理。
好用的用戶端模式
- 第一次 POST 之前先產生金鑰,同一個邏輯工作的逾時重試都復用它。
- 成功之後檢查
Idempotency-Replayed: true,就能知道這次回應是又跑了一遍,還是來自快取。 - 檔案、op 或參數一變就換金鑰,即使主體沒變。
- 對
/api/v1/pipeline,一把金鑰覆蓋整次 POST,而不是內部每一個步驟。
重放不是什麼
重放不是持久化的佇列。儲存是行程內的(互斥鎖保護的 HashMap),TTL 為 24 小時。過期之後,或者行程重啟丟掉這份記憶體對映之後,同一個金鑰會把 op 再跑一遍。多實例部署不共享這張對映,除非你在前面加一層共享儲存;目前的 middleware 是每個行程一份。
把 Idempotency-Replayed: true 當成「這次回應來自快取」的證明,而不是永久帳本。它不表示 PDF 被重新處理過,也不會延長 TTL。
更細的介面說明見 開發者 與 為 AI Agent 而建。壓縮 PDF 這類工具頁仍可用於不必發明金鑰的瀏覽器一次性工作。