조용한 API 킬러: 캐싱이 내 통합을 망친 이유와 해결 방법

Source: Dev.to

Problem

최근 이틀 동안 머신‑투‑머신 API 연동에서 발생한 “유령”을 잡으려 애썼습니다. 스테이징에서는 연동이 완벽히 동작했지만, 프로덕션에서는 중요한 서드‑파티 서비스의 웹훅 엔드포인트가 영수증을 가끔씩 인식하지 못해 중복 처리와 이벤트 누락이 발생했습니다. 서드‑파티 로그에는 우리 엔드포인트가 200 OK 응답을 보냈다고 나오지만, 우리 로그에는 해당 백그라운드 작업이 전혀 실행되지 않았습니다. 이 문제는 간헐적이며 로컬에서 재현할 수 없었는데, 이는 상태나 환경 문제의 전형적인 징후였습니다.

Root Cause

철저한 로깅을 진행한 결과, 프로덕션 API 게이트웨이(우리가 제어하지 못하는 레이어)가 POST 요청을 과도하게 캐싱하고 있음을 발견했습니다. 우리 idempotency‑key 헤더가 일정 기간 동안 정적이었기 때문에(비즈니스 로직상 이벤트를 그룹화하기 위한 결정), 게이트웨이는 동일한 POST 요청에 대해 애플리케이션 서버에 도달하기도 전에 캐시된 200 응답을 반환했습니다. 결과적으로 애플리케이션은 요청을 전혀 보지 못했고, 작업도 큐에 넣어지지 않았습니다. 게이트웨이에서 온 “정상적인” 200 응답은 비즈니스 로직 전체가 실패했음을 가려냈습니다.

Fix

1. 캐시 지시문 추가 – 해당 웹훅 엔드포인트에 Cache-Control: no-store 헤더를 추가해 모든 중간 캐시가 저장을 건너뛰도록 했습니다.
2. idempotency 전략 수정 – 이벤트당 진정으로 고유한 idempotency‑key를 사용하도록 설계를 변경해, 모든 요청이 구별되고 캐시될 수 없게 만들었습니다.

Takeaways

• 특히 GET이 아닌 요청에 대해서는 모든 프록시, CDN, 게이트웨이 레이어에서 캐시 동작을 반드시 검증하세요.
• 다운스트림 캐시에서 반환되는 성공적인 HTTP 상태 코드는 치명적인 거짓일 수 있습니다.
• 캐시 헤더를 API 설계에서 일급 요소로 다루세요; “GET”이라고 생각하는 작업이라도 네트워크에서는 “캐시 가능한” 작업으로 해석될 수 있으며, 그 가정이 시스템을 조용히 무너뜨릴 수 있습니다.