외부 저장은 끝났는데 뒤따르는 요청이 실패하면 자동화 전체가 멈출 수 있습니다. 이때는 저장 결과부터 대조해 재실행할 단계를 정합니다. 아마존웹서비스(AWS)는 타임아웃·재시도 설명에서 타임아웃이나 실패가 발생했어도 원격 변경은 이미 적용됐을 수 있다고 설명합니다.
CMS 저장 뒤 캐시 갱신이 실패한 기록
2026년 10월 14일 UTC의 콘텐츠 발행 기록에는 콘텐츠 관리 시스템(CMS)의 저장 결과가 남아 있습니다. 뒤이어 보낸 사이트 캐시 갱신 요청은 HTTP 429로 실패했고, 작업은 cache-pending 상태로 기록됐습니다. 조사한 발행 프로그램에서 이 이름은 CMS 저장 뒤 캐시 갱신을 기다리는 상태를 가리킵니다.
발행 코드는 CMS 쓰기, 사이트 캐시 갱신, 공개 페이지 확인을 별도 단계로 처리합니다. Sanity의 트랜잭션 설명에 따르면 한 트랜잭션 안의 변경은 모두 성공하거나 모두 실패합니다. 이 발행 코드의 캐시 갱신은 CMS 트랜잭션이 끝난 뒤 보내는 별도 요청이므로, 저장 성공 뒤에도 실패할 수 있습니다.
10월 15일에 보존된 운영 기록과 코드를 읽었으며, 기록의 캐시 갱신 상태는 대기 중이었습니다. 실제 서비스에 재개 요청을 보내거나 이후 공개 화면 반영을 확인하는 작업은 이번 조사에 포함되지 않았습니다.
저장 내용과 실행 상태로 재개 지점 고르기
같은 발행 작업을 재개하는 코드는 준비한 문서가 이전 실행 뒤 바뀌지 않았는지 검사합니다. 그 문서에 들어 있는 각 필드를 CMS에서 다시 읽은 값과 대조하고, 일치하면 CMS 쓰기를 건너뛰고 후속 단계로 갑니다. 값이 다르면 자동으로 다시 쓰지 않습니다.
다음 표는 10월 15일 확인한 발행 코드와 Sanity의 수정 조건을 바탕으로 정리한 재개 판단입니다. 실제 운영 기록에서 확인한 상태는 첫 행의 캐시 갱신 대기입니다.
| 멈춘 상태 | 먼저 대조할 내용 | 대조 뒤 진행 |
|---|---|---|
| CMS 저장 기록이 있고 캐시 갱신 실패 | 준비한 문서와 CMS의 해당 필드가 일치하는지 | 일치하면 캐시 갱신부터 재개 |
| 저장 요청의 성공 여부를 확인하지 못함 | 대상 문서가 있고 요청한 내용과 일치하는지 | 저장 확인 시 후속 단계로 이동, 확인 안 되면 재전송 중단 |
| 수정하려던 원본 문서의 버전 변경 | 다시 읽은 최신 문서와 원래 수정안 | 새 원본을 기준으로 수정안 재검토 |
문서 버전(revision)은 그 문서가 수정됐는지 확인하는 값입니다. Sanity의 동시 수정 제어 설명에 따르면 수정 요청에 넣은 ifRevisionID 값과 현재 문서의 revision이 같을 때만 수정이 적용됩니다. 그사이 다른 수정이 있으면 409 Conflict로 거부되며, 새 문서를 읽고 변경 내용을 다시 검토할 수 있습니다.
코드의 mutation-uncertain은 저장 요청의 성공 여부를 알 수 없는 상태를 뜻합니다. 조사한 운영 기록에서는 이 상태의 실제 발생 사례를 찾지 못했고, 확인 근거는 코드와 모의 테스트입니다. 이 분기는 대상 내용이 일치한다고 확인되기 전에는 쓰기를 반복하지 않도록 막습니다.
10월 15일 Windows 11·Node v24.21.0에서 실행한 기존 모의 단위 테스트 8개는 모두 통과했습니다. 캐시 실패 후 재개를 검증한 테스트에서는 처음 저장을 포함해 CMS 쓰기 호출이 합계 1회로 유지됐습니다. 외부 API 대신 메모리 안의 가짜 클라이언트를 사용한 시험으로, 실제 네트워크 장애 복구까지 검증한 결과는 아닙니다.
이 사례에서는 마지막으로 확인된 외부 상태, 오류가 난 단계, 다음에 허용할 행동을 함께 남기면 재개 판단에 쓸 수 있습니다. 모델 호출과 도구 실행이 섞인 작업에서도 에이전트 관측성은 기록을 연결해 문제가 생긴 지점을 찾는 데 쓰입니다.
멱등 키의 효과는 API별 처리 규칙에 달려 있습니다
재시도(retry)는 실패했거나 결과를 받지 못한 요청을 다시 보내는 동작입니다. HTTP 표준 RFC 9110의 멱등성 정의는 같은 요청을 여러 번 보냈을 때 서버에 의도한 효과가 한 번 보낸 경우와 같은 성질을 말합니다. 응답은 매번 달라질 수 있습니다.
같은 표준은 비멱등 요청을 자동 재시도하려면 그 요청이 실제로 멱등하게 처리됨을 알거나, 원래 요청이 적용되지 않았음을 확인할 수 있어야 한다고 설명합니다. 오류 메시지만으로 저장 작업을 다시 실행할지 정하기 어려운 이유입니다.
멱등 키(Idempotency-Key)는 서버가 같은 작업의 재요청임을 알아보도록 보내는 식별값입니다. Stripe의 멱등 요청 문서에 따르면 API v1은 실행이 시작된 첫 요청의 상태 코드와 본문을 저장합니다. 같은 키로 재요청하면 500 오류도 저장된 결과를 돌려주며, 파라미터가 달라지면 오류가 납니다.
같은 문서는 API v1에서 입력 검증에 실패하거나 실행 중인 다른 요청과 충돌해 처리가 시작되지 않으면 멱등 결과를 저장하지 않는다고 설명합니다. 이 API의 키는 최소 24시간이 지난 뒤 제거될 수 있으며, 제거된 키를 다시 쓰면 새 요청으로 처리됩니다.
같은 작업을 재시도할 때마다 새 키를 발급하면 이전 요청의 재시도임을 그 키로 식별할 수 없습니다. 멱등 키는 동일 요청의 중복 처리를 다루고, Sanity의 revision 조건은 읽은 뒤 문서가 바뀌었는지를 검사합니다.
승인 범위와 재시도 중단 기준
조사한 발행 코드는 발행 권한 표시와 최종 검수본의 내용·스키마 버전을 확인한 뒤 실제 쓰기를 진행합니다. 입력이 바뀌면 기존 검수 결과를 그대로 적용할 수 없습니다. 이 구조를 운영에 적용하면 이미 허용된 같은 작업은 저장된 입력과 승인 범위를 검사해 이어가고, 대상·내용·행동이 범위를 벗어나면 새 판단을 거치도록 정할 수 있습니다.
AI 에이전트의 도구 호출과 검증을 관리하는 에이전트 하네스에서도 승인 확인을 실제 외부 변경 직전에 두는 방식으로 실행 범위를 제한할 수 있습니다.
AWS의 재시도·백오프 설명은 재시도 자체가 실패한 서버의 부하를 늘릴 수 있다고 지적합니다. 지수 백오프(exponential backoff)는 재시도할 때마다 대기 시간을 지수적으로 늘리는 방식이고, 지터(jitter)는 간격에 무작위 차이를 주어 여러 요청이 동시에 몰리는 현상을 줄입니다. 같은 문서는 여러 계층이 각각 재시도하면 호출 수가 곱해질 수 있다는 점도 설명합니다.
운영자는 API 정책과 실패 종류에 맞춰 재시도 간격의 상한, 최대 시도 횟수, 작업 전체 기한을 함께 정하는 편이 좋습니다. 하위 클라이언트가 이미 수행하는 재시도까지 포함해 실제 요청 횟수를 계산하고, 저장 상태를 확인하지 못했거나 승인 범위가 달라졌다면 자동 실행을 중단합니다. 중단 시점에는 확인된 상태와 남은 오류를 기록해 다음 판단에 넘깁니다.
자료 확인 기준: 2026년 10월 15일. API의 재시도 규칙과 키 보존 정책은 바뀔 수 있습니다.