Idempotency-Key: PDF 작업을 안전하게 재시도하기
/api/v1/ 아래 POST 작업에 Idempotency-Key를 보내면 PDF123이 성공 응답을 24시간 동안 프로세스 로컬 메모리에 캐시하고, 작업을 두 번 실행하는 대신 Idempotency-Replayed: true를 설정합니다.

multipart PDF 업로드에서 네트워크 타임아웃과 클라이언트 재시도는 흔한 일입니다. 멱등 키가 없으면 두 번째 POST가 같은 병합이나 OCR, 압축을 다시 돌려 업로드와 처리 시간을 통째로 낭비하게 됩니다. Idempotency-Key가 있으면 PDF123이 첫 성공 응답을 대신 재생할 수 있습니다.
미들웨어가 하는 일
pdfx-server의 서버 미들웨어는 변경형 호출에만 적용됩니다. /api/v1/ 아래 경로(/api/v1/pipeline 포함)로 가는 POST입니다. GET과 다른 메서드는 그대로 통과합니다. 요청에 Idempotency-Key 헤더가 없거나 trim 후 비어 있으면, op는 캐시 조회 없이 정상 실행됩니다.
헤더가 있을 때:
- 저장소는 주체 + 키로 항목을 식별합니다. 주체는
X-API-KEY에서(key:…형태), 없으면Authorization에서(auth:…형태), 둘 다 없으면 리터럴anon입니다. 이 두 값을 SHA-256으로 해시해 맵 키를 만들고, 요청 본문은 키에 들어가지 않습니다. - 24시간 안에 캐시가 맞으면 미들웨어는 저장된 상태 코드와 콘텐츠 타입, 콘텐츠 디스포지션, 본문을 반환하고 **
Idempotency-Replayed: true**를 설정합니다. - 맞지 않으면 요청이 진행됩니다. 성공한 응답만 버퍼링해 저장합니다(비성공 응답은 재생용으로 캐시되지 않습니다).
- 응답 본문은 100 MiB까지 버퍼링해 재생할 때 파일 바이트를 다시 보낼 수 있게 합니다. 버퍼링할 수 없는 본문은 캐시를 조용히 건너뛰지 않고, 그 요청이 HTTP 500을 반환합니다. 즉 한도를 넘는 응답은 캐시 없이 통과하는 대신 실패합니다.
실패한 작업은 같은 키로 안전하게 재시도할 수 있습니다. 실패는 저장되지 않으므로 다음 시도가 성공하면 그것이 캐시 결과가 됩니다. 다른 파일이나 매개변수에 같은 키를 재사용하지는 마세요. 캐시는 본문을 해시하지 않고 주체와 키만 봅니다. API 키도 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 키 호출자 모두 됩니다. 워터마크 뒤에 압축을 잇는 파이프라인도 중복 제거하려는 HTTP 요청마다 키를 하나 보내야 합니다. 단계별로 POST하면 각 단계마다, /api/v1/pipeline 한 번으로 호출하면 그 한 번에 키 하나입니다.
도구 페이지의 브라우저 일회성 작업(PDF 압축, OCR 등)은 키를 만들어 낼 필요가 없습니다. 이 헤더는 재시도하는 클라이언트에 중요합니다. 공개 skill /skills/pdf123.md이 같은 이유로 pipeline 예제에 Idempotency-Key를 넣어 두었습니다.
잘 동작하는 클라이언트 패턴
- 첫 POST 전에 키를 만들고, 그 논리적 작업의 타임아웃 재시도에 재사용합니다.
- 성공 시
Idempotency-Replayed: true를 확인하면 이 응답이 op를 다시 실행한 것인지 캐시에서 온 것인지 알 수 있습니다. - 파일이나 op, 매개변수가 바뀌면 주체가 같아도 키를 바꿉니다.
/api/v1/pipeline에서는 내부 단계마다가 아니라 pipeline POST 전체에 키 하나가 적용됩니다.
재생이 아닌 것
재생은 지속성 있는 작업 큐가 아닙니다. 저장소는 프로세스 로컬(뮤텍스 뒤의 HashMap)이고 TTL은 24시간입니다. 만료 후나, 메모리 맵을 버리는 프로세스 재시작 후에는 같은 키가 op를 다시 실행합니다. 다중 인스턴스 배포는 앞에 공유 저장소를 두지 않으면 이 맵을 공유하지 않습니다. 지금의 미들웨어는 프로세스마다 하나입니다.
Idempotency-Replayed: true는 이 응답이 캐시에서 왔다는 증거로 다루고, 영구 원장으로 다루지 마세요. PDF가 다시 처리됐다는 뜻도 아니고 TTL을 늘려 주지도 않습니다.
더 자세한 표면 설명: 개발자와 AI 에이전트를 위해 만들어진 API. PDF 압축 같은 도구 페이지는 키를 만들 필요 없는 브라우저 일회성 작업에 그대로 쓸 수 있습니다.