외부 API 연동 안정화 체크리스트 : Instagram API 사례로 정리

최근에 Instagram API 연동을 필요로 하는 프로젝트를 진행하면서 Instagram API 연동 with Instagram Login 이라는 글을 썼다. 단순 구현을 하면서 점차 기술적으로 고민이 들었던 부분들을 리서치 하고 기록해보려고한다.

 

# Instagram API 연동, “기능 구현” 다음에 보이기 시작한 운영 관점의 고민들

 처음에는 단순했다.

 Instagram API를 붙이고, 필요한 데이터를 받아와서 DB에 저장하면 기능은 완성이라고 생각했다.

 

그런데 시간이 지나고 다시 코드를 보니, 이건 “동작하는 기능”일 뿐이지 아직 “안정적으로 운영할 수 있는 기능”은 아니었다.

외부 API를 호출하는 순간부터 내 애플리케이션은 더 이상 내부 로직만 신경 쓰면 되는 구조가 아니고, 지연, 실패, 중복 호출, 데이터 최신화 지연, DB 자원 점유, 관측 불가 같은 문제를 같이 안고 간다는 걸 뒤늦게 체감했다.

 

이번 글은 누군가를 가르치기 위한 정답 정리라기보다, 내가 Instagram API 연동을 운영 관점에서 다시 보면서 어떤 부분을 고민하게 되었는지 남겨두는 기록에 가깝다.

 

———

 

## 왜 이 고민을 하게 됐는가

 

지금 내 프로젝트는 Instagram API를 연동해서 데이터를 조회하고, 필요한 값은 DB에 저장하는 흐름까지는 구현된 상태다.

하지만 당시에는 MVP 기한이 정해져있었기에 기능 구현이 우선이었고, 외부 API 호출에서 흔히 필요한 안정화 요소들은 거의 고려하지 않았다.

 

예를 들면 이런 것들이다.

 

- 타임아웃

- 실패 분류

- 재시도 여부

- 멱등성

- DB 트랜잭션과 외부 호출 분리

- 로깅/모니터링

 

처음에는 이런 고민들이 MSA 환경에서나 필요한 얘기라고 막연하게 생각했는데, 자료를 찾아보면서 그건 아니라는 걸 알게 됐다.

MSA는 이런 문제가 더 자주, 더 크게 드러나는 환경일 뿐이고, 사실 모놀리식이어도 외부 API를 호출하는 순간부터는 이미 분산 시스템의 일부 문제를 안고 가게 된다.

 

즉, 내 프로젝트가 MSA가 아니더라도 외부 API를 호출하고 있다면, 안정적인 운영을 위해 위 항목들을 생각해야 하는 건 자연스러운거다.

 

———

 

## 1. Instagram 인사이트 데이터는 실시간이 아니다

 

가장 먼저 눈에 띈 건 인사이트 데이터의 최신화 시점이었다.

 

처음 메모할 때는 “Instagram 인사이트 지표는 최대 48시간이 걸린다”라고 적어뒀다.

이 표현은 방향은 맞지만, 조금 더 조심스럽게 쓰는 게 좋다. 현재 확인 가능한 자료들을 보면, Instagram 인사이트 데이터는 실시간이 아니며 일부 지표는 최대 48시간 정도 지연될 수 있다고 이해하는 게 더 적절하다.

 

이게 왜 중요하냐면, 같은 요청을 다시 보냈는데 데이터가 전과 똑같이 돌아왔다고 해서 곧바로 우리 시스템이 잘못됐다고 단정할 수 없기 때문이다. Instagram 쪽 집계 자체가 아직 갱신되지 않았을 가능성도 충분히 있다.

 

즉, 인사이트 데이터는 내부 DB 조회처럼 “지금 요청했으니 지금 시점의 최신 데이터가 오겠지”라고 생각하면 안 된다. 이 특성을 이해하지 못하면, 정상적인 지연을 장애처럼 오해하거나 반대로 실제 문제를 놓칠 수도 있다.

 

### 참고 링크

 

- Meta Docs: Instagram Media Insights Reference (https://developers.facebook.com/docs/instagram-platform/reference/instagram-media/insights

 

———

 

## 2. Instagram API는 호출량 제한도 고려해야 한다

 

Instagram API를 붙일 때 흔히 놓치기 쉬운 부분 중 하나가 호출량 제한이다. 처음에는 단순히 “요청만 보내면 응답을 주는 API”처럼 생각하기 쉽지만, Meta Graph API 계열은 호출량이 무한정 허용되는 구조가 아니다. 호출량이 많아지면 rate limiting이나 throttling이 걸릴 수 있고, 이 경우 일부 요청은 실패하거나 지연될 수 있다.

 

여기서 중요한 건 호출 제한이 단순히 “분당 몇 번”처럼 고정된 숫자 하나로 끝나지 않는다는 점이다. Meta 문서를 보면 제한은 앱 수준, 사용자/토큰 수준, 그리고 비즈니스 사용 방식에 따라 다르게 적용될 수 있다. 즉 개발자는 “우리 서비스는 하루에 이 정도만 호출하니까 괜찮겠지”라고 막연히 생각하기보다, 실제 운영 중에 어느 시점부터 usage가 높아지는지를 관측할 수 있어야 한다.

 

이게 왜 중요하냐면, 처음에는 트래픽이 적어서 문제가 없더라도 기능이 늘어나고 동기화 대상이 많아지면 같은 API를 호출하는 횟수가 빠르게 증가 할 수 있기 때문이다. 특히 인사이트 조회나 미디어 목록 조회처럼 여러 계정, 여러 콘텐츠를 순회하는 구조라면 요청 수가 생각보다 쉽게 커진다. 이런 구조에서 호출량 제한을 고려하지 않으면, 운영 중 특정 시점에 갑자기 일부 요청이 막히거나 응답이 불안정해질 수 있다.

 

즉 Instagram API 연동은 “응답이 오는가”만 볼 게 아니라, “얼마나 자주 호출하고 있고, 그 호출량이 제한에 가까워지고 있는가”도 같이 봐야 한다. 이 특성을 이해하지 못하면, 평소에는 잘 동작하다가 트래픽이 몰리거나 수집 범위가 커졌을 때 예상하지 못한 장애를 맞을 수 있다.

 

### 참고 링크

 

  - Meta Docs: Graph API Rate Limiting (https://developers.facebook.com/docs/graph-api/overview/rate-limiting#platform-rate-limits)

 

———

 

## 3. 외부 API는 성공/실패 두 가지로만 나눌 수 없다

 

외부 API 연동을 다시 보면서 가장 크게 느낀 건, 네트워크 요청은 생각보다 애매한 상황이 많다는 점이었다.

 

예를 들어 timeout이 발생했다고 하자.

이때 가능한 경우는 여러 가지다.

 

- 요청이 Instagram 서버에 아예 도달하지 않았을 수도 있다.

- 요청은 도달했지만 처리 중이었을 수도 있다.

- 이미 처리는 끝났는데 응답만 받지 못했을 수도 있다.

 

이런 상황을 그냥 전부 “실패”라고 처리해버리면, 실제로는 이미 처리된 요청을 또 보내게 되거나, 중복 저장 같은 문제로 이어질 수 있다.

그래서 외부 API를 다룰 때는 단순히 성공/실패만 보는 게 아니라, 경우에 따라서는 알 수 없음(unknown) 상태까지 생각해야 한다는 점이 인상적이었다.

 

이 관점은 카카오페이 글을 보면서 더 명확해졌다.

결제 같은 민감한 도메인은 더 극단적이지만, 핵심은 똑같다. 외부 시스템과 통신할 때는 “응답이 안 왔다 = 처리 안 됐다”로 단정하면 안 된다.

 

다만 내 프로젝트는 결제처럼 외부 시스템의 상태를 직접 바꾸는 요청이 아니라, 아직은 조회 API 중심의 구조다.

그래서 취소 API나 보상 트랜잭션까지 당장 필요한 상황은 아니지만, 그래도 실패 분류 자체는 반드시 필요하다고 느꼈다.

 

  ### 참고 링크

 

  - 카카오페이: MSA 환경에서 네트워크 예외를 잘 다루는 방법 (https://tech.kakaopay.com/post/msa-transaction/)

  - AWS Builders’ Library: Timeouts, retries, and backoff with jitter (https://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/)

 

———

 

## 4. 느린 외부 API는 결국 우리 서비스 전체를 느리게 만든다

 

Instagram 서버가 완전히 죽는 경우만 문제가 되는 건 아니다.

오히려 실무에서는 “죽지는 않았는데 엄청 느린 상태”가 더 골치 아플 수도 있다.

 

이럴 때 타임아웃이 없으면, 우리 서버는 외부 API 응답을 하염없이 기다리게 된다.

요청 처리 스레드는 계속 묶이고, 응답 시간은 길어지고, 같은 요청이 쌓이면 전체 서비스가 느려질 수 있다.

 

게다가 그 호출 구간 안에 DB 트랜잭션까지 같이 들어 있으면 문제가 더 커진다.

외부 API가 느린 동안 DB 커넥션까지 계속 잡고 있게 되고, 요청이 많아지면 커넥션 풀 고갈 같은 2차 장애로 번질 수 있다.

 

그래서 타임아웃은 단순히 “조금 기다리다 포기하는 옵션”이 아니라, 외부 시스템 지연이 우리 시스템 전체 자원 고갈로 전파되지 않게 막는 보호 장치에 가깝다.

 

### 참고 링크

 

  - AWS Builders’ Library: Timeouts, retries, and backoff with jitter (https://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/)

 

———

 

## 5. 재시도는 무조건 넣는다고 좋은 게 아니다

 

처음에는 외부 API가 실패하면 “그냥 한 번 더 호출하면 되지 않을까?”라고 생각하기 쉽다.

그런데 자료를 보다 보니, 재시도는 생각보다 훨씬 조심스럽게 다뤄야 하는 영역이었다.

 

재시도는 일시적인 네트워크 오류나 순간적인 장애에는 도움이 될 수 있다.

하지만 모든 예외에 무조건 재시도를 걸어버리면 오히려 장애 상황에서 요청을 더 몰아넣는 형태가 된다.

 

이른바 retry storm 같은 안티패턴이다.

 

예를 들어 Instagram 서버가 이미 느리거나 불안정한 상태인데, 우리 서버가 같은 요청을 여러 번 다시 보내기 시작하면 상대 서버도 더 힘들어지고, 우리 쪽 스레드와 응답 시간도 더 악화될 수 있다.

그래서 재시도는 “실패하면 다시”가 아니라, “어떤 실패에 한해, 몇 번까지, 어떤 간격으로 다시 시도할 것인가”를 정해서 써야 한다.

 

### 참고 링크

 

  - Azure Architecture: Retry Storm antipattern (https://learn.microsoft.com/ko-kr/azure/architecture/antipatterns/retry-storm/)

 

———

 

## 6. 멱등성은 “조회”보다 “저장/동기화”에서 더 중요하다

 

내가 처음 메모할 때는 “인사이트 지표는 언제 최신화될지 모르니까, 계속 받아와도 이게 맞는 최신 데이터인지 모른다. 그러면 멱등성을 어떻게 유지해야 하지?”라고 적어뒀다.

 

이 고민의 방향은 맞았지만, 표현은 조금 더 정확히 다듬는 게 좋겠다고 느꼈다.

멱등성은 보통 조회 요청 자체보다, 그 조회 결과를 저장하고 동기화하는 작업 쪽에서 더 중요하다.

 

즉, 중요한 질문은 이런 쪽이다.

 

- 같은 인사이트 데이터를 여러 번 받아와도 DB 상태가 꼬이지 않는가

- 같은 동기화 작업이 중복 실행돼도 최종 결과가 동일한가

- 사용자가 버튼을 여러 번 누르거나 배치가 중복 실행돼도 중복 저장이 발생하지 않는가

 

인사이트 데이터처럼 최신화 시점이 불명확한 경우에는, 같은 데이터가 반복해서 들어오는 것이 정상일 수도 있다.

그래서 이럴수록 “같은 요청이 여러 번 왔다” 자체보다 “그 결과를 저장하는 로직이 중복에 안전한가”를 보는 게 더 중요하다.

 

그리고 이 지점에서 로깅/모니터링과도 연결된다.

똑같은 데이터가 들어왔을 때, 그게 Instagram 집계 지연 때문인지, 우리 동기화 로직의 중복 실행 때문인지 구분하려면 호출 이력과 저장 이력이 보여야 하기 때문이다.

 

### 참고 링크

 

  - 카카오페이: MSA 환경에서 네트워크 예외를 잘 다루는 방법 (https://tech.kakaopay.com/post/msa-transaction/)

 

———

 

## 7. DB 트랜잭션과 외부 API 호출은 분리하는 편이 안전하다

 

이번에 찾아본 내용 중 가장 실무적으로 바로 와닿았던 건, 외부 API 호출과 DB 트랜잭션을 가능한 한 분리하라는 이야기였다.

 

처음에는 “어차피 외부 응답을 보고 DB 처리할 건데, 결국 연결된 거 아닌가?” 싶었는데, 핵심은 외부 API 결과를 참고하느냐가 아니라, DB 트랜잭션을 언제 시작하느냐였다.

 

예를 들어 이런 구조가 있다고 하자.

 

- 외부 API 호출

- 응답 대기

- 응답 결과를 바탕으로 DB 조회/저장

 

이 흐름 자체는 자연스럽다.

문제는 이 전체가 하나의 @Transactional 메서드 안에 들어 있을 때다.

 

그렇게 되면 메서드 진입 순간 트랜잭션이 열리고, 외부 API가 3초 걸리면 그 3초 동안 DB 트랜잭션도 살아 있을 수 있다.

결과적으로 DB 커넥션이 불필요하게 오래 점유되고, 트래픽이 커지면 커넥션 풀 고갈 위험이 생긴다.

 

그래서 더 안전한 구조는:

 

- 외부 API 호출은 트랜잭션 없이 먼저 수행하고

- 그 응답 결과를 받은 뒤에

- 필요한 DB 작업만 짧게 트랜잭션으로 묶는 방식이다

 

이렇게 하면 외부 시스템의 지연이 DB 자원 점유로 전파되는 걸 줄일 수 있다.

 

### 참고 링크

 

  - 카카오페이: 주니어 서버 개발자가 유저향 서비스를 개발하며 마주쳤던 이슈와 해결 방안 (https://tech.kakaopay.com/post/troubleshooting-logs-as-a-junior-developer/)

 

———

 

## 8. 로깅과 모니터링은 “문제를 고치는 장치”가 아니라 “문제를 보이게 하는 장치”다

 

처음에는 타임아웃, 재시도, 트랜잭션 분리 같은 기술적인 해결책에 더 눈이 갔다.

그런데 정작 운영 관점에서 더 중요한 건, 지금 어떤 문제가 발생하고 있는지 관측할 수 있느냐였다.

 

외부 API 연동은 문제가 생겨도 원인이 바로 드러나지 않는다.

 

- 우리 서버 문제인지

- Instagram API 문제인지

- 단순 지연인지

- 같은 데이터가 반복해서 들어오는 이유가 최신화 지연인지, 저장 로직 문제인지

 

이런 걸 구분하려면 결국 로그와 메트릭, 그리고 필요하다면 헬스 체크 지표가 있어야 한다.

 

특히 인사이트 데이터처럼 “정상인데 늦을 수 있는” 연동은 더 그렇다.

데이터가 갱신되지 않았다는 사실 자체가 장애는 아닐 수 있으므로, 호출 시각, 응답 시간, 상태 코드, 예외 유형, 저장된 데이터의 기준 시각같은 정보가 함께 보여야 원인을 해석할 수 있다.

 

즉 단순히 “성공했는가 / 실패했는가”만 보는 것이 아니라, 외부 의존성이 지금 얼마나 느린지, 실패율이 높아지고 있는지, 우리 애플리케이션이 그 영향을 받고 있는지까지 볼 수 있어야 한다.

 

이 부분은 Health Endpoint Monitoring pattern을 보면서 더 정리가 됐다.

운영에서는 단순히 애플리케이션이 살아 있는지만 보는 게 아니라, 그 애플리케이션이 의존하고 있는 구성요소들까지 함께 봐야 한다. 내 프로젝트로 치면, 서버 프로세스가 살아 있는 것만으로는 충분하지 않고, Instagram API 호출이 정상적으로 이뤄지는지, 외부 API 응답 시간이 급격히 느려지지는 않았는지, 실패가 특정 구간에서 몰리고 있지는 않은지까지 같이 봐야 의미가 있다.

 

그래서 로깅/모니터링은 장애를 직접 막아주는 기능이라기보다, 문제를 더 빨리 발견하고, 원인을 좁히고, 대응할 수 있게 해주는 기반이라고 이해하게 됐다.

 

결국 외부 API 연동에서 중요한 건 “장애가 났을 때 고치는 능력”만이 아니라, 장애 징후를 먼저 볼 수 있는 능력이라는 생각이 들었다.

 

### 참고 링크

 

  - Azure Architecture: Health Endpoint Monitoring pattern

    (https://learn.microsoft.com/en-us/azure/architecture/patterns/health-endpoint-monitoring)

 

———

 

## 지금 시점에서 내가 우선적으로 점검할 항목

 

모든 안정화 패턴을 한 번에 다 넣는 건 현실적이지 않다. 프로젝트를 진행하면서, 이제 2차 MVP에 들어갈 기능들도 구현해야돼서 시간도 없을테고 구현 난이도가 있을거같아 조사하면서도 어떻게, 어디서부터 해야될지 막막했다.

결론은, 2차 MVP 기능 구현을 우선으로 하면서 안정화 작업을 후순위로 조금씩 해나가면 좋을거같다.

 

안정화 작업에 들어가게된다면, 지금 내 프로젝트 상황에서는 아래 다섯 가지를 먼저 정리하는 게 맞다고 보고 있다.

 

- 타임아웃

    - 외부 API 지연이 전체 서비스 자원 고갈로 이어지지 않게 하기 위해

- 실패 분류

    - 일시적 실패와 영구 실패를 구분하기 위해

- 재시도 여부

    - 무조건 재시도하지 않고, 특정 조건에만 제한적으로 적용하기 위해

- DB 트랜잭션과 외부 호출 분리

    - 외부 응답 대기 시간이 DB 커넥션 점유 시간까지 길어지지 않게 하기 위해

- 로깅/모니터링

    - 문제를 빨리 감지하고 원인을 좁히고 정책의 효과를 검증하기 위해

 

반대로, 벌크헤드, 서킷 브레이커, 이중화 같은 항목은 지금 당장 필수라기보다, 트래픽 규모와 장애 영향도를 보면서 다음 단계에서 검토할 수 있는 주제라고 생각한다.

 

———

 

이번에 정리하면서 느낀 건, 외부 API 연동은 “호출해서 값 받아오기”에서 끝나는 문제가 아니라는 점이었다.  오히려 그 다음부터가 진짜 시작이었다.

 

Instagram API를 붙여서 기능이 돌아가는 것과, 장애와 지연을 견디면서 안정적으로 운영할 수 있는 것은 완전히 다른 문제였다.

지금 내 프로젝트는 아직 후자 쪽으로 가는 과정에 있고, 이 글은 그 과정에서 내가 어떤 포인트를 먼저 봐야 하는지 정리한 기록이다.