타임아웃은 실패 확정이 아니다: AI 에이전트의 중복 결제·발송을 막는 멱등성 설계

 

AI 에이전트가 결제나 이메일 발송 도구를 호출한 뒤 타임아웃을 만났다고 해서 실제 작업까지 실패한 것은 아니다. 서버는 이미 처리했지만 응답만 돌아오지 않았을 수 있다. 이때 에이전트가 새 요청으로 다시 실행하면 중복 결제, 중복 주문, 중복 발송이 발생할 수 있다.

 

이 문제를 줄이는 핵심 개념이 멱등성, 즉 Idempotency다. 같은 업무 요청을 다시 전달하더라도 추가적인 효과가 발생하지 않도록 만드는 성질이다. 프롬프트에 “한 번만 실행하라”고 적는 것에 더해, 도구와 서버가 요청의 정체성과 처리 상태를 관리해야 한다.

 

이 글은 AI 에이전트의 재시도와 도구 호출, 멱등성 키, 체크포인트, 외부 상태 확인, 보상 처리와 평가 방법을 연결해 설명한다. 토스페이먼츠와 pxd의 국내 기술 글, AWS Builders’ Library, LangGraph 공식 문서를 비교하고 실제 업무에 적용할 수 있는 설계 예시를 정리했다.

 

핵심 요약

 

• 타임아웃은 호출자가 결과를 제때 받지 못했다는 뜻이며 서버의 실패 확정과 다르다.

 

• 같은 업무의 재시도에는 같은 식별자를 유지하고 새로운 업무에는 새로운 식별자를 사용해야 한다.

 

• 멱등성 키를 헤더에 붙여도 서버가 처리하지 않으면 중복 실행은 막히지 않는다.

 

• 체크포인트 복원과 외부 시스템의 중복 효과 방지는 서로 다른 문제다.

 

• 재시도 횟수보다 먼저 오류 유형, 현재 상태, 업무 기한과 권한을 확인해야 한다.

 

읽을 순서

 

① 타임아웃과 멱등성의 정확한 의미

② 업무 식별자와 서버의 중복 처리 계약

③ 재시도·체크포인트·외부 상태의 연결

④ 가상 주문 사례와 평가·운영 지표

⑤ 도입 체크리스트와 FAQ

 

1. “응답 없음”을 “실행 안 됨”으로 해석하는 순간

 

 

가상의 주문 에이전트가 외부 쇼핑 시스템에 주문 생성을 요청했다고 가정하자. 서버는 주문을 저장했지만 응답이 돌아오는 구간에서 네트워크 문제가 생겼다. 에이전트는 오류만 보고 같은 상품을 다시 주문한다. 두 번째 요청이 새로운 주문으로 처리되면 사용자는 주문 두 건을 갖게 된다.

 

반대로 첫 요청이 서버에 도착하지 않았을 수도 있다. 호출자 입장에서 보이는 타임아웃은 같지만 실제 상태는 다르다. 그러므로 타임아웃이라는 예외 이름 하나만 보고 성공과 실패를 확정하면 안 된다. 결과가 확인되지 않은 상태를 별도로 표현할 필요가 있다.

 

이 문제는 AI가 등장하기 전부터 분산 시스템에서 다뤄 왔다. AWS의 ‘Making retries safe with idempotent APIs’도 응답을 받지 못한 호출자가 리소스 생성 여부를 알 수 없고, 단순 재시도로 여러 리소스가 만들어질 수 있는 상황을 설명한다.[1]

 

AI 에이전트에서는 모델이 도구 오류를 읽고 다음 행동을 스스로 고른다는 점이 추가된다. SDK가 이미 재시도했는데 모델이 다시 호출할 수 있고, 프로세스 재시작 후 같은 업무를 새 작업으로 이해할 수도 있다. 모델의 판단과 프로그램의 재시도 정책을 하나의 실행 구조 안에서 봐야 한다.

 

2. 멱등성은 같은 응답 문자열을 뜻하지 않는다

 

멱등성은 같은 작업을 반복했을 때 의도한 서버 상태나 효과가 한 번 수행한 경우와 같게 유지되는 성질이다. “알림 상태를 읽음으로 설정한다”는 작업은 여러 번 수행해도 읽음 상태다. 반면 “현재 값을 반대로 바꾼다”는 토글 작업은 반복할 때마다 상태가 달라진다.

 

 

여기서 응답의 모든 글자가 반드시 같아야 하는 것은 아니다. 삭제 요청을 처음 보냈을 때와 다시 보냈을 때 응답 코드가 다르더라도 대상이 삭제된 상태라는 의도한 효과는 같을 수 있다. 조회도 다른 사용자의 변경 때문에 값이 달라질 수 있다. 조회가 멱등하다는 말이 데이터가 영원히 고정된다는 뜻은 아니다.

 

HTTP 메서드의 의미와 개별 서비스 구현도 구분해야 한다. PUT이나 DELETE는 멱등한 의미를 갖도록 정의돼 있지만 실제 API가 그 의미를 지키는지 확인해야 한다. POST도 별도의 업무 계약과 중복 처리 로직을 통해 특정 작업에 멱등성을 제공할 수 있다.

 

멱등성과 안전성 역시 같은 개념은 아니다. 삭제는 멱등할 수 있어도 데이터를 변경한다. 토스페이먼츠의 기술 글은 이 차이와 멱등성 키를 이용한 API 설계를 설명한다.[2] 에이전트가 사용할 도구를 분류할 때 읽기 전용인지, 반복해도 효과가 같은지, 되돌릴 수 있는지를 각각 확인하면 좋다.

 

3. 국내 기술 블로그에서 가져올 원칙과 주의점

 

토스페이먼츠는 결제 결과를 받지 못한 상황과 중복 요청을 예로 들어 멱등성의 필요성을 설명한다. 같은 키의 요청 기록을 확인하고 이미 처리된 결과를 반환하는 흐름, 키의 보관 기간, 같은 키에 다른 본문이 들어오는 상황을 함께 다룬다.[2]

 

pxd의 기술 글은 고유 식별자와 동시성 제어, 데이터베이스 제약 조건 등을 소개한다.[3] 중복 처리 문제를 API 하나에 한정하지 않고 데이터와 상태 변경의 관점에서 생각하는 데 참고할 만하다. 다만 각 기법이 해결하는 문제가 같지는 않다.

 

 

낙관적 동시성 제어는 오래된 버전으로 덮어쓰는 충돌을 막는 데 유용하고, 멱등성 키는 같은 업무를 반복 적용하는 문제를 다룬다. 캐시는 조회 비용을 줄일 수 있지만 캐시를 붙였다는 사실만으로 쓰기 작업의 중복 효과가 사라지지는 않는다. 여러 기법을 하나의 만능 해결책으로 묶으면 설계가 모호해진다.

 

일상 비유도 구체적으로 써야 한다. “켜기” 버튼은 반복해도 켜짐 상태지만 “누를 때마다 켜짐과 꺼짐을 바꾸는” 스위치는 그렇지 않다. 에이전트 도구도 상태를 지정하는 기능인지, 현재 상태를 바꾸는 명령인지에 따라 재시도 위험이 달라진다.

 

4. 멱등성 키는 도구 호출 번호가 아니라 업무의 정체성이다

 

한 업무를 실행하기 위해 여러 네트워크 호출이 발생할 수 있다. 각각의 호출 시도는 서로 다른 번호를 가져도 되지만 같은 업무의 재시도라는 사실은 유지돼야 한다. 멱등성 키를 호출할 때마다 새로 만들면 서버는 반복 요청을 서로 다른 작업으로 받아들일 수 있다.

 

예를 들어 하나의 주문을 만드는 작업에는 주문 생성용 업무 식별자를 부여한다. 응답 지연으로 같은 주문 생성을 다시 보낼 때는 그 식별자를 유지한다. 사용자가 실제로 두 번째 주문을 추가로 요청한 경우에는 새로운 업무로 식별해야 한다.

 

요청 본문이 같다고 반드시 같은 의도는 아니다. 같은 상품을 같은 수량으로 두 번 사고 싶을 수 있다. AWS 자료도 동일한 매개변수로 리소스를 두 개 만들려는 의도가 있을 수 있으므로 본문의 해시만으로 중복을 판단하는 방식에는 한계가 있다고 설명한다.[1]

 

 

에이전트 시스템에서는 검증된 실행 계층이 업무 식별자를 생성하고 보관하는 방식이 합리적이다. 모델이 자연어 설명을 조금 바꾸거나 다시 계획을 세웠다는 이유로 새로운 실행 키가 생기지 않게 한다. 다만 시스템이 어디에서 업무를 확정하는지는 제품의 요청·승인 흐름에 맞춰 정해야 한다.

 

5. 같은 키에 다른 금액이 들어오면 어떻게 할까

 

멱등성 키만 같고 금액, 수신자, 상품 수량이 바뀌면 같은 업무를 다시 보낸 것인지 의심해야 한다. 이런 요청을 기존 성공 결과로 조용히 처리하면 사용자는 바뀐 값이 반영됐다고 오해할 수 있다. 반대로 새로운 작업처럼 실행하면 키의 의미가 무너진다.

 

서버는 중복 확인의 범위를 명확히 정의해야 한다. 어느 사용자나 조직의 어떤 작업 유형 안에서 키가 고유한지, 중요한 요청 필드가 같은지 확인한다. 같은 키가 다른 계정이나 다른 API에서 어떤 의미인지도 서비스 계약에 포함해야 한다.

 

토스페이먼츠 글은 처리 중인 요청과 같은 키가 들어오는 경우, 같은 키에 다른 본문이 들어오는 경우를 오류 시나리오로 구분한다.[2] 구체적인 상태 코드와 처리 규칙은 API별 문서를 확인해야 한다. 한 서비스의 예시를 모든 도구가 따르는 표준 동작처럼 가정하면 안 된다.

 

승인과도 연결된다. 사용자가 검토한 결제 금액이나 수신자가 바뀌었다면 기존 실행 계획과 승인 상태가 그대로 유효한지 확인해야 한다. 멱등성은 권한을 부여하는 기능이 아니다. 같은 요청을 중복 처리하지 않는 것과 해당 요청을 실행해도 되는지는 별도로 검사해야 한다.

 

6. 헤더에 키만 붙이면 끝나지 않는다

 

 

클라이언트가 키를 보낸다고 서버가 자동으로 중복을 막는 것은 아니다. 서버가 그 키를 지원하고 어떤 결과를 얼마나 보관하며 처리 중인 요청을 어떻게 다루는지 알아야 한다. 지원하지 않는 외부 API에 임의의 헤더를 추가해도 보장이 생기지 않는다.

 

일반적인 설계에서는 업무 키와 요청 정보, 상태, 결과를 영속적으로 관리한다. 같은 키가 오면 완료 결과를 반환하거나 진행 상태를 알려준다. 새로운 키라면 처리 권한을 확보한 뒤 실행한다. 여러 요청이 동시에 도착해도 하나만 실행 경로에 들어가도록 해야 한다.

 

가장 조심할 구간은 효과가 발생하는 시점과 기록을 저장하는 시점 사이의 틈이다. 실제 주문을 만든 뒤 완료 기록을 쓰기 전에 프로세스가 죽으면 다음 요청이 다시 주문을 만들 수 있다. 반대로 기록만 남기고 작업은 수행하지 못하면 정상 요청이 영원히 완료되지 않을 수 있다.

 

같은 데이터베이스 안의 변경이라면 트랜잭션과 고유 제약으로 원자성을 설계할 수 있다. AWS 자료도 요청 식별자의 기록과 관련 상태 변경을 원자적으로 처리하는 중요성을 설명한다.[1] 하지만 외부 결제나 이메일 시스템까지 하나의 로컬 트랜잭션으로 묶을 수 있다고 가정해서는 안 된다.

 

7. 동시 요청·프로세스 중단·늦은 요청까지 포함해야 한다

 

중복 요청을 순서대로 두 번 보내는 테스트만으로는 부족하다. 첫 요청이 아직 실행 중일 때 두 번째 요청이 동시에 도착할 수 있다. 단순히 “기록이 없으면 실행하고 나중에 저장”하는 코드는 두 요청이 모두 기록 없음으로 판단하는 경합을 만들 수 있다.

 

 

고유 제약, 원자적 상태 전이, 잠금이나 임대 같은 기법을 업무에 맞게 사용할 수 있다. 다만 잠금을 잡은 프로세스가 중단됐을 때 누가 언제 이어받을지도 정해야 한다. 잠금 만료만으로 외부 작업이 실패했다는 뜻은 아니므로 실행 여부를 다시 대조할 필요가 있다.

 

키와 결과의 보관 기간도 중요하다. 기록을 지운 뒤 늦은 재시도가 도착하면 새 작업으로 처리될 수 있다. 보관 기간은 메모리 비용만 보고 정하기보다 재시도 가능 기간, 업무 기한, 외부 시스템의 조회 범위와 함께 결정해야 한다.

 

작업 결과가 나중에 다른 사용자에 의해 취소되거나 삭제된 경우도 있다. 과거 요청의 재전달을 새 실행으로 바꿔 버리면 사용자가 취소한 상태를 되돌릴 수 있다. 과거 요청의 결과와 현재 리소스 상태를 구분하는 계약이 필요하다. AWS 자료 역시 늦게 도착하는 요청을 별도의 경계 사례로 다룬다.[1]

 

8. 재시도는 오류 유형과 남은 시간에 따라 결정한다

 

일시적인 네트워크 장애와 잘못된 입력은 다르게 처리해야 한다. 잠깐의 연결 문제는 재시도로 해결될 수 있지만 존재하지 않는 필수 값이나 권한 거부는 같은 요청을 반복해도 해결되지 않을 수 있다. 오류 문구 하나보다 도구의 구조화된 상태와 API 계약을 확인하는 편이 낫다.

 

재시도 가능한 오류도 무한히 반복해서는 안 된다. 최대 시도 수, 전체 마감 시간, 호출 간격, 서비스가 안내한 대기 시간 등을 정한다. 지수 백오프는 시도 사이의 간격을 늘리고 지터는 여러 호출자가 같은 순간에 다시 몰리는 현상을 줄이는 데 활용할 수 있다.

 

 

이 정책은 중복 효과를 막는 멱등성과 서로 보완한다. 백오프로 천천히 보낸다고 중복 주문이 사라지는 것은 아니다. 반대로 중복을 막더라도 지나친 재시도는 외부 시스템 부하와 비용을 키울 수 있다. 두 문제를 각각 설계해야 한다.

 

인증이나 권한이 거부됐을 때 다른 계정과 도구를 찾아 같은 작업을 밀어붙이는 식의 복구는 적절하지 않다. 권한 문제와 일시 장애를 구분해 실행을 보류하고 필요한 정보를 전달해야 한다. 복구 경로가 원래의 권한 범위를 벗어나지 않게 한다.

 

9. SDK·워크플로·모델이 각각 재시도하면 횟수가 불어난다

 

에이전트가 한 번 호출했다고 보이는 동작 안에서 SDK가 여러 번 요청했을 수 있다. 그 밖의 워크플로 엔진과 모델도 실패를 보고 다시 호출하면 중첩된 재시도가 생긴다. 각 계층이 독립적으로 “최대 세 번”이라고 정해도 전체 호출 수는 세 번으로 제한되지 않는다.

 

가령 바깥 작업이 세 번 실행되고 각 실행 안에서 실제 요청이 세 번 발생한다면 단순한 가정에서 최대 아홉 번의 요청이 생길 수 있다. 이는 계산을 설명하기 위한 가상 예시이며 실제 제품의 기본 설정이나 측정 결과가 아니다. 여러 단계가 더해지면 추적이 어려워질 수 있다.

 

따라서 재시도 책임과 예산을 명시해야 한다. 네트워크 수준의 짧은 복구는 SDK가 맡고 업무 상태 판단은 실행 계층이 맡는 등 역할을 정할 수 있다. 어떤 구조를 택하든 같은 업무 식별자가 계층 사이에서 유지되고 실제 시도 수가 집계돼야 한다.

 

모델에게도 도구 결과의 의미를 분명하게 전달해야 한다. 실행 실패가 확정됐는지, 진행 중인지, 결과를 아직 확인하지 못했는지 구분한다. “오류가 났으니 다시 해 보라”는 하나의 메시지로 모든 상황을 묶으면 모델이 불필요한 재실행을 선택하기 쉽다.

 

 

10. 체크포인트는 외부 결제를 되돌리지 않는다

 

LangGraph 공식 문서는 체크포인터가 스레드의 그래프 상태를 저장하고, 스토어가 스레드를 넘어서는 정보를 저장하는 역할을 구분한다. 또한 메모리 기반 저장은 프로세스 재시작 후 체크포인트를 유지하지 못하므로 운영 환경에 맞는 영속 저장을 선택해야 한다고 설명한다.[4]

 

체크포인트는 에이전트가 어디까지 진행했는지 복원하는 데 도움을 준다. 하지만 외부 시스템에 이미 전달된 결제나 발송을 자동으로 취소하는 장치는 아니다. 그래프 안의 상태와 외부 업무 상태는 서로 다른 저장 경계에 있을 수 있다.

 

LangGraph의 장애 허용 문서는 재시도, 시도별 타임아웃, 재시도 소진 후 오류 처리의 조합을 설명한다.[5] 문서가 실패한 시도의 내부 쓰기를 정리한다고 설명하더라도 외부 API가 발생시킨 효과까지 모두 되돌린다는 뜻으로 읽으면 안 된다.

 

재개할 노드에 외부 작업이 들어 있다면 재실행 시 어떤 효과가 생기는지 검토해야 한다. 성공한 외부 요청의 업무 식별자와 결과를 함께 보관하고, 복원 후 같은 업무가 이미 처리됐는지 확인하는 흐름이 필요하다. 기억을 복원하는 문제와 한 번만 효과를 내는 문제를 따로 봐야 한다.

 

11. 정확히 한 번이라는 말에는 경계를 붙여야 한다

 

메시지를 한 번만 보내겠다는 약속과 실제 업무 효과가 한 번만 발생한다는 약속은 다르다. 요청 전달, 큐 처리, 데이터베이스 반영, 외부 발송 중 어느 구간에 대한 보장인지 확인해야 한다. 한 구간의 보장을 전체 서비스의 보장으로 확대하면 안 된다.

 

 

같은 데이터베이스 안에서는 처리 기록과 업무 변경을 하나의 트랜잭션으로 묶는 방법을 검토할 수 있다. 데이터베이스와 외부 메시지 발행을 연결할 때는 아웃박스 같은 패턴이 유용할 수 있다. 그러나 아웃박스가 최종 수신 시스템의 중복 처리를 자동으로 없애는 것은 아니다.

 

외부 API가 멱등성 기능을 제공하면 그 계약을 활용한다. 제공하지 않더라도 업무 식별자로 처리 결과를 조회할 수 있다면 재시도 전에 대조할 수 있다. 생성 기능만 있고 처리 상태 조회도 불가능한 도구는 결과가 모호해졌을 때 자동 복구의 범위가 제한된다.

 

이 한계는 숨기기보다 제품에 표현하는 편이 좋다. “결과 확인 중” 상태를 유지하고 담당자에게 대조 정보를 넘기는 것이 무조건 재실행하는 것보다 나을 수 있다. 모든 상황을 즉시 성공이나 실패로 압축하는 인터페이스는 불확실성을 위험한 행동으로 바꿀 수 있다.

 

12. 외부 상태 조회도 식별 기준이 있어야 한다

 

결제 목록에 같은 금액이 있다고 첫 요청이 성공했다고 단정할 수는 없다. 다른 정상 거래일 수 있기 때문이다. 주문과 발송도 제목이나 시간만으로 대조하면 비슷한 작업을 잘못 연결할 수 있다. 외부 시스템이 반환한 거래 식별자나 업무 참조값을 이용하는 편이 낫다.

 

조회 결과의 최신성도 확인해야 한다. 외부 서비스에 따라 방금 생성한 결과가 목록에 즉시 나타나지 않을 수 있다. 한 번 조회해서 없었다는 이유만으로 반드시 미실행이라고 결론 내리는 것은 위험하다. 해당 서비스의 상태 전파와 조회 계약을 알아야 한다.

 

대조 과정은 실행 상태와 분리해 기록할 수 있다. 외부 요청 접수, 처리 진행, 완료 확인, 미실행 확정, 확인 불가 같은 상태를 구분한다. 이 상태 이름이 곧 정답은 아니지만 무엇을 확인했고 무엇을 모르는지 표현하는 것이 중요하다.

 

 

최종 완료 보고는 모델의 자신감보다 실제 증거에 연결해야 한다. 외부 거래 번호와 조회 결과, 처리 시점 같은 확인 가능한 근거를 남기면 이후 조사도 쉬워진다. 사용자에게는 내부 로그 전체를 보여주기보다 완료된 일과 확인 중인 일을 명확히 구분해 전달하면 된다.

 

13. 보상 처리는 시간을 되돌리는 롤백과 다르다

 

여러 시스템이 참여하는 업무는 중간 단계만 성공할 수 있다. 재고는 예약됐지만 결제가 확정되지 않거나, 주문은 생성됐지만 발송을 시작하지 못한 경우다. 이때 업무 규칙에 따라 예약 해제나 환불 같은 보상 동작을 수행할 수 있다.

 

하지만 보상은 과거가 없었던 상태로 완벽하게 되돌리는 작업과 다르다. 이미 발송된 이메일을 삭제할 수 없고 환불에는 수수료와 처리 시간이 생길 수 있다. 외부에서 본 기록이나 알림도 남을 수 있다. 무엇을 복구할 수 있는지 구체적으로 정해야 한다.

 

보상 동작 자체도 중복될 수 있으므로 멱등성이 필요할 수 있다. 같은 예약 해제나 같은 환불을 반복해도 추가 효과가 생기지 않도록 별도의 업무 키와 상태를 관리한다. 원래 작업의 실패가 확정되지 않은 상황에서 무작정 보상을 실행하면 또 다른 불일치를 만들 수 있다.

 

또한 코드가 상태 문자열을 ‘보상 완료’로 바꿨다고 실제 환불이 끝난 것은 아니다. LangGraph 문서의 간단한 오류 처리 예시를 사용할 때도 그래프 상태 변경과 외부 보상 호출을 구분해야 한다.[5] 실제 효과와 확인 근거가 있어야 완료라고 보고할 수 있다.

 

14. 가상 주문 에이전트에 적용하는 실행 흐름

 

 

다음은 실제 사고 기록이 아닌 설계 예시다. 사용자가 정해진 상품 한 건의 주문을 요청했다고 하자. 시스템은 상품과 수량, 배송 대상, 권한을 확인하고 확정된 업무 식별자를 저장한다. 승인 절차가 필요한 환경이라면 구체적인 주문 내용과 승인 상태를 연결한다.

 

주문 생성 호출에는 외부 API가 지원하는 멱등성 계약을 적용한다. 응답이 정상이라면 외부 주문 식별자와 상태를 저장한다. 타임아웃이면 바로 새 주문을 만들지 않고 같은 업무의 처리 여부를 조회하거나 지원되는 같은 키로 재시도하는 정책을 따른다.

 

진행 중이라는 결과가 오면 업무 기한 안에서 상태를 확인한다. 외부 처리 실패가 확정되면 원인을 분류해 허용된 재시도 또는 종료로 이동한다. 결과를 확인할 수 없다면 확인 불가 상태를 남기고 중복 실행을 피하면서 대조할 자료를 전달한다.

 

예시 상태 흐름

 

요청 확인 → 업무 식별자 저장 → 실행 허용 확인 → 외부 요청

외부 완료 확인 → 결과 저장 → 사용자에게 완료 보고

일시 오류 또는 응답 미수신 → 처리 상태 대조 → 계약에 따른 제한적 재시도

권한 오류 또는 잘못된 입력 → 실행 보류·수정 요청

확인 불가 → 대조 정보와 함께 담당자 인계

 

이 흐름은 특정 프레임워크의 코드가 아니라 설계 점검용이다. 실제 구현에서는 서버가 중단되는 위치, 동시 요청, 키의 보관 기간, 외부 시스템의 조회 기능을 반영해야 한다. 화살표가 깔끔하다는 사실만으로 실행의 원자성이 보장되지는 않는다.

 

15. 테스트는 정상 호출보다 실패하는 틈을 겨냥한다

 

첫 번째 테스트는 외부 작업이 성공한 직후 응답만 유실되는 상황이다. 같은 업무를 다시 전달했을 때 효과가 두 번 발생하지 않는지 확인한다. 실패 메시지를 잘 보여주는지보다 실제 주문이나 발송 건수가 어떤 상태인지가 핵심이다.

 

 

두 번째는 동시에 같은 키의 요청을 보내는 경우다. 세 번째는 외부 효과가 발생한 뒤 완료 기록을 저장하기 전에 프로세스를 중단하는 경우다. 재시작 후 어느 상태에서 이어가고 무엇을 다시 확인하는지 관찰한다. 같은 프로세스의 메모리만 보고 중복을 막는 구현은 이런 시험에서 한계가 드러난다.

 

그밖에 같은 키와 다른 본문, 다른 사용자와 같은 키, 보관 기간이 지난 키, 지연 도착 요청, 오류 뒤의 사용자 취소를 포함할 수 있다. 정상적으로 같은 상품을 두 번 주문하려는 요청도 넣어 잘못된 중복 차단이 없는지 확인한다.

 

실험은 모의 결제와 테스트용 수신자, 통제된 환경에서 수행한다. 실제 고객에게 중복 발송하거나 실제 거래를 만들어 시험할 이유는 없다. 결과에는 최종 상태, 실제 효과 횟수, 대조 기록, 시도 수, 소요 시간을 함께 남긴다.

 

평가 지표는 업무 성공률, 중복 효과 발생률, 정상 요청의 잘못된 차단, 확인 불가 상태 비율, 사람 개입 시간, 복구 비용을 포함할 수 있다. 재시도 후 성공이 늘더라도 중복 피해와 장시간 대기가 커졌다면 개선이라고 단정하기 어렵다.

 

16. 운영 전에 확인할 체크리스트

 

• 업무 식별자와 개별 호출 시도 식별자를 구분하는가?

• 같은 업무의 재시도에서 멱등성 키가 유지되는가?

• 같은 키와 다른 요청 내용을 서버가 구분하는가?

• 동시 요청과 프로세스 중단에도 중복 처리가 막히는가?

• 외부 API가 실제로 제공하는 멱등성 범위와 보관 기간을 확인했는가?

• 결과가 불명확할 때 조회·대조할 경로가 있는가?

• SDK와 워크플로, 모델의 재시도 예산이 연결돼 있는가?

• 체크포인트의 상태와 외부 업무 상태를 각각 확인하는가?

• 취소·승인 변경·보상 처리도 별도의 실행 규칙을 갖는가?

• 최종 완료 보고를 실제 외부 결과에 연결하는가?

 

 

도입은 읽기 작업과 범위가 좁은 쓰기 작업부터 시작할 수 있다. 실제로 중복되면 손실이 큰 기능을 연결하기 전에 테스트 가능한 실행 계약을 마련한다. 도구 호출을 더 잘하는 프롬프트와 안전하게 실행되는 도구는 서로 보완해야 한다.

 

AI 에이전트의 신뢰성은 오류 없이 말하는 능력만으로 결정되지 않는다. 결과를 받지 못했을 때 무엇을 알고 무엇을 모르는지 표현하고, 같은 업무를 다시 시도하더라도 추가 효과를 만들지 않도록 설계하는 데서 운영의 차이가 생긴다.

 

자주 묻는 질문

 

Q1. 프롬프트에 한 번만 실행하라고 쓰면 충분한가요?

 

도움은 될 수 있지만 네트워크 재시도와 프로세스 재시작, 동시 요청을 서버 수준에서 막지는 못한다. 업무 식별자와 처리 기록, 외부 API 계약이 함께 필요하다. 모델의 기억만으로 중복 효과를 보장해서는 안 된다.

 

Q2. UUID를 매번 새로 만들면 중복을 막을 수 있나요?

 

새로운 업무를 구분하는 데는 유용하지만 같은 업무의 재시도에서 새 키를 만들면 중복 방지가 깨질 수 있다. 한 번 확정된 업무에는 같은 키를 유지해야 한다. 어떤 요청이 같은 업무인지 먼저 정의하는 것이 중요하다.

 

Q3. GET 응답이 바뀌면 멱등하지 않은 것인가요?

 

그렇지 않다. 다른 작업자가 데이터를 변경하면 조회 결과는 달라질 수 있다. 멱등성은 같은 요청의 반복으로 의도한 효과가 추가되는지를 다루며, 응답 데이터가 영원히 같다는 뜻은 아니다.

 

Q4. 체크포인트를 저장하면 외부 실행도 정확히 한 번 되나요?

 

자동으로 그렇지는 않다. 체크포인트와 외부 시스템의 저장 경계가 다를 수 있다. 재개할 때 외부 효과가 중복되지 않도록 도구의 멱등성과 결과 대조를 설계해야 한다.

 

Q5. 외부 서비스가 멱등성 키를 지원하지 않으면 어떻게 하나요?

 

 

업무 참조값으로 결과를 조회하거나 실행 계층에서 상태를 대조할 수 있는지 확인한다. 조회와 중복 방지 기능이 모두 없다면 자동 재실행의 범위를 제한하고 확인 불가 상태를 인계해야 할 수 있다. 지원하지 않는 헤더를 붙이는 것으로 보장이 생기지는 않는다.

 

Q6. 재시도 횟수는 몇 번이 적절한가요?

 

보편적인 정답은 없다. 오류 유형, 업무 기한, 외부 서비스 제한, 중복 효과 방지 계약에 따라 정해야 한다. 최대 횟수와 전체 시간 예산을 두고 실제 복구율과 비용을 측정하는 편이 좋다.

 

참고 자료와 확인 범위

 

[1] Amazon Builders’ Library, Malcolm Featonby, Making retries safe with idempotent APIs.

https://aws.amazon.com/builders-library/making-retries-safe-with-idempotent-APIs/

references-details-empty

호출자 제공 요청 식별자, 의미가 동등한 응답, 원자적 처리와 늦게 도착하는 요청에 관한 설계를 참고했다. 개별 AWS API의 계약을 모든 서비스의 보장으로 일반화하지 않았다.

 

[2] 토스페이먼츠 개발자센터, 멱등성이 뭔가요?, 2023.01.11.

https://docs.tosspayments.com/blog/what-is-idempotency

멱등성이 뭔가요? | 토스페이먼츠 개발자센터

HTTP 안전성과 멱등성의 구분, 결제 API의 키 처리와 오류 시나리오를 확인했다. 예시 상태 코드와 키 범위는 실제 연동하는 API 문서를 다시 확인해야 한다.

 

 

[3] pxd XE Blog, 강영민, 멱등성, 본문 표기 2024.10.31.

https://tech.pxd.co.kr/post/멱등성-257

pxd XE Blog | 멱등성

국내 기술 블로그에서 다루는 고유 식별자와 동시성 제어, 데이터 제약의 관점을 참고했다. 캐시와 멱등성, 상태 지정과 토글의 차이는 본문에서 구분했다.

 

[4] Docs by LangChain, Persistence.

https://docs.langchain.com/oss/python/langgraph/persistence

Persistence - Docs by LangChain

체크포인터와 스토어의 범위, 메모리 기반 체크포인트의 재시작 한계를 확인했다.

 

[5] Docs by LangChain, Fault tolerance.

https://docs.langchain.com/oss/python/langgraph/fault-tolerance

Fault tolerance - Docs by LangChain

재시도·타임아웃·오류 처리의 구분과 조합을 참고했다. 구체적인 API와 지원 조건은 사용하는 라이브러리 버전의 문서를 확인해야 한다.

 

자료 확인일: 2026년 10월 17일. 주문 흐름과 수치 계산, 체크리스트는 공개 자료를 바탕으로 작성한 가상 설계 예시다. 직접 측정한 사고율이나 특정 기업의 실제 중복 결제 사례를 주장하는 내용이 아니다.