성공적인 데모는 통합을 운영 준비가 된 것처럼 보이게 할 수 있습니다. 하지만 실제 트래픽은 그 간극들을 드러냅니다. 배포 후 2주 만에, 결제 제공업체로부터 증가한 지연 시간(latency)이 재시도(retries)의 누적을 유발했고, 결과적으로 세 고객에게 중복 청구되었습니다. 이는 운영 통합에서 잘 알려진 위험입니다. 소프트웨어 통합 코드가 실제 환경 조건 하에서 실행될 때 발생하는 흔한 결과입니다.
같은 패턴은 다양한 제품 전반에 걸쳐 나타납니다: 핀테크 개발 회사로 구축된 결제 백엔드, 물류 분야의 인공지능(AI)를 사용하는 라우팅 엔진, 또는 갑자기 유료 고객을 끌어모으는 AI 프로토타이핑 서비스를 통해 만들어진 MVP(Minimum Viable Product). 프로토타입은 성공하기 위해 API 호출 한 번만 필요합니다. 하지만 운영 시스템은 상황이 잘못될 때도 이를 처리해야 합니다. 처음에는 저렴해 보이지만 몇 달 안에 비용이 많이 발생하는 5가지 통합 실수를 소개합니다.
API 버전 관리 및 계약(Contract) 문제
파트너가 필드 이름이나 날짜 형식을 변경했습니다. 스키마 검사(schema checks)가 없다면, 코드는 페이로드(payload)를 수락하고 데이터베이스에 null 값을 기록합니다. 낮은 데이터 일관성(data consistency)은 재무 보고서가 원본 기록과 동기화되지 않은 상태로 남겨둘 수 있습니다.
데이터 문제를 조기에 포착하세요. 모든 인바운드 페이로드를 스키마와 검증하고, 유효성 검사(validation)에 실패하면 처리를 중단해야 합니다:
견고한 API 버전 관리 정책의 모습
- 최초부터 API 경로(/v1/)나 헤더에서 버전 관리를 수행하고, 단일 소비자(consumer)가 사용하더라도 마찬가지입니다.
- 제거된 필드나 타입 변경을 하위 호환성 깨짐 변화(breaking changes)로 간주하세요. 이러한 변경 사항은 새로운 API 버전에만 도입하고, 이전 버전에 대해서는 폐기 기간(deprecation period)을 두어야 합니다.
- Pact나 스키마 차이(schema diffs)를 사용하여 CI에서 계약 검사(contract checks)를 자동화하여, 공급자 측의 하위 호환성 깨짐 변화가 초기에 감지되고 프로덕션에 도달하는 것을 방지하세요.
명확한 API 버전 관리 규칙은 소프트웨어 유지보수 비용도 절감합니다. 소비자가 업그레이드 시점을 통제하므로, 금요일 밤의 급작스러운 파서 수정 같은 것은 거의 불가능해집니다.
클라우드 통합에서 타임아웃 및 무분별한 재시도(Blind Retries) 누락의 위험성
HTTP 타임아웃이 없으면 느린 서비스들이 워커와 연결을 점유합니다. 클라우드 통합 환경에서는 단 50개의 워커만으로도 몇 초 안에 용량에 도달할 수 있으며, 외부 종속성이 너무 느려서 API가 새로운 요청을 처리하지 못하게 됩니다.
제안되는 설정:
- 1~3초의 연결 타임아웃(connection timeout)과 서비스의 p99 지연 시간보다 높은 읽기 타임아웃(read timeout)을 설정하세요.
- 재시도 타임아웃, 502–504 오류, 그리고
Retry-After를 포함하는 429 응답에 대해 적용하세요.
- 재시도를 3~4회로 제한하고 지터(jitter)가 있는 지수 백오프(exponential backoff)를 사용하세요.
- 각 사용자 요청에 대한 전체 마감 시간(overall deadline)을 설정하여 재시도가 호출자(caller)의 시간 제한 내에 완료되도록 보장하세요.
자주 실패하는 종속성(dependencies)은 서킷 브레이커(circuit breaker)로 감싸세요. 좋은 클라우드 통합 설계는 모든 원격 호출이 멈출 수 있다고 가정하며, 그럴 경우 사용자에게 무엇을 보여줄지 미리 결정합니다.
계속 읽기 전에 간단히 확인해 보세요: 가장 바쁜 세 가지 통합의 HTTP 클라이언트 구성을 열고 타임아웃 값을 찾아보세요. 만약 값이 없다면, 그것이 월요일에 해야 할 첫 번째 수정 사항입니다.
소프트웨어 통합에서 속도 제한(Rate Limits) 무시하기
야간 백필(backfill) 작업이 10만 개의 CRM 레코드를 전송하여 초당 100 요청 제한을 초과했습니다. 반복된 429 에러로 인해 API 키가 한 시간 동안 정지되어 결제 동기화(checkout sync)가 오프라인 상태가 되었습니다. API 자동화 스크립트나 백필 작업은 테스트 환경에서 프로덕션 환경으로 이동할 때 종종 속도 제한을 초과합니다.
쿼터(quota)를 공유 자원으로 취급하세요:
- API 한도를 사전에 확인하고 응답 헤더(response headers)를 적용하여 요청 페이싱(request pacing)을 제어합니다.
- 토큰 버킷 리미터(token-bucket limiter)를 제공업체가 명시한 최대치 중 보수적인 속도, 즉 약 90%로 설정합니다.
- 자격 증명(credentials)을 분리하거나 대량 작업(bulk job)의 우선순위를 낮춤으로써 실시간 요청에 높은 우선순위를 부여합니다.
- 여러 서비스가 쿼터를 공유하는 경우 게이트웨이 또는 통합 플랫폼 수준에서 속도 제한을 설정합니다. 소프트웨어 통합에서 속도 제한은 지연 시간이나 페이로드 크기처럼 설계 입력값(design input)입니다.
API 쓰기 작업 시 Idempotency 생략 방지
만약 POST /payments가 10초 후에 타임아웃되면, 클라이언트는 첫 번째 요청이 성공했는지 알지 못한 채 재시도할 수 있습니다. 두 요청 모두 처리될 경우, 고객에게 이중 청구가 발생합니다. 유사한 문제는 중복 주문, 배송 건, 이메일 등을 생성할 수 있습니다.
재시도는 해당 작업에 Idempotency가 내장되어 있을 때만 안전합니다.
Idempotency 키 추가 방법
클라이언트는 비즈니스 작업당 하나의 키를 생성하여 모든 재시도 시 Idempotency-Key 헤더에 전송합니다. 서버는 이 키 아래 첫 번째 결과를 저장하고, 반복될 경우 해당 결과를 반환합니다.
서버 측에서 확인(check)과 쓰기(write)는 원자적(atomic)이어야 합니다. 그렇지 않으면 두 개의 병렬 재시도가 모두 “아직 키가 없다”고 인식하여 카드에 이중 청구를 발생시킵니다.
멱등성 키(idempotency keys)는 가장 긴 재시도 창(retry window)을 넘어서까지 유지하고, 다른 페이로드(payload)를 사용하는 요청으로 키를 재사용하는 경우 거부해야 합니다. Stripe의 API 문서는 이 접근 방식에 대한 성숙한 예시를 제공합니다. 재시도 로직을 도입하기 전에 엔드포인트 자체에 멱등성을 구축하세요.
“모든 외부 API는 언젠가 느리거나, 잘못되거나, 다운될 것이라고 가정하세요. 좋은 통합 코드는 이미 각 경우에 어떻게 해야 하는지 알고 있습니다.”
— Denis Salatin
관측 가능성(Observability)이 없는 얕은 API 모니터링
건강한 모니터링에도 불구하고, 창고 주문 동기화가 4시간 동안 중단되었습니다. 코드는 경고를 기록하고 오류를 노출하는 대신 빈 목록을 반환했습니다. 고객이 보고하기 전까지 이 실패는 눈에 띄지 않았습니다.
필수적인 API 모니터링 지표:
- 상태 코드별 HTTP 오류율, 그리고 p95 및 p99 지연 시간(latency).
- 시간당 재시도 횟수와 속도 제한 응답(429) 횟수.
- 주문 동기화 건수 등 통합당 최소한 하나의 비즈니스 지표를 사용하고, 이 수치가 0으로 떨어지면 경고가 발생하도록 합니다. API 관측 가능성을 사용하여 조용한 실패 감지하기
통합이 실패했다는 것을 아는 것은 첫 번째 단계일 뿐입니다. API 관측 가능성은 어디서 그리고 왜 문제가 생겼는지 정확히 찾아내는 데 도움을 줍니다. 상관관계 ID(correlation ID)를 모든 구간에 전파하고, 비밀 정보와 카드 데이터를 제외하면서 요청 및 응답 메타데이터를 기록하며, OpenTelemetry를 사용하여 서비스 간 실패한 주문을 추적하세요. 실패 메시지는 데드 레터 큐(dead-letter queue)에 넣어 필요한 컨텍스트로 조사하고 재실행할 수 있게 합니다. 좋은 API 관측 가능성은 파트너 장애의 원인을 단 10분 만에 찾아낼 수 있도록 도와줍니다. 모든 사고가 발생한 후에는, 이를 더 빨리 감지하거나 진단하는 데 도움이 되었을 신호로 API 모니터링 대시보드를 업데이트하세요.
출시 전 체크리스트
운영 환경에서 프로덕션 트래픽을 외부 API로 라우팅하기 전에 다음 안전장치들을 확인하세요:
- 모든 수신 페이로드에 버전화된 스키마 유효성 검사(Versioned schema validation)가 적용됩니다.
- 모든 아웃바운드 요청은 타임아웃과 지터(jitter)를 갖는 제한된 재시도 정책(bounded retry policy)을 가집니다.
- 클라이언트 측 스로틀링(Client-side throttling)이 각 제공업체의 속도 제한(rate limit)보다 아래에 위치합니다.
- 상태 변경을 일으키는 모든 POST 요청은 재시도가 안전합니다.
- 각 통합에는 담당자, 비즈니스 지표, 그리고 데드레터 큐(dead-letter queue)가 있습니다.
이 다섯 가지 실수들은 모두 하나의 근본 원인을 공유합니다. 바로 마감 기한 압박 속에서 결정되었고 재검토되지 않은 통합 아키텍처입니다. 엔터프라이즈 소프트웨어 개발에서, 통합은 종종 주변 시스템들보다 더 오래 살아남습니다. 솔루션 아키텍처 검토는 각 외부 API를 담당자와 운영 매뉴얼(runbook)을 가진 위험 요소로 취급해야 합니다. 이 습관은 어떤 엔터프라이즈 아키텍처 관행에도 적용되며, 방지하는 첫 번째 사고만으로도 그 가치를 증명합니다.
_이 다섯 가지 중 팀에게 가장 큰 비용을 초래한 것은 무엇인가요? 해결책과 함께 스토리를 댓글로 남겨주세요.
