API 연동이 릴리즈에서만 깨질 때

운영 중에는 작은 이상 신호도 빨리 분리해서 봐야 한다. API 연동 문제는 한 단어만 붙잡지 않고 요청/응답 전체 흐름에서 원인을 좁혀야 한다.

재현 조건, 로그, 응답처럼 눈으로 확인할 수 있는 값을 먼저 모는 게 중요하다. 그래야 다음 수정이 명확해진다.

정상 상태를 먼저 정의하기

로컬과 배포 환경에서 API 응답이 다를 수 있다. 정상 상태가 뭔지 미리 정해야 문제를 판단할 수 있다.

• 로컬: API 호출 성공, 응답 코드 200
• 배포: API 호출은 되지만 특정 필드가 없음
• 배포: API 호출 실패, 응답 코드 401

각 환경에서 뭐가 다른지 명확하게 기록한다.

첫 번째 단서: 인증 상태

API 인증이 문제일 가능성이 높다. 토큰이나 API 키가 정상인지 확인한다.

• 배포 환경의 환경변수가 맞는가
• 토큰 갱신 로직이 정상인가
• 요청 헤더에 인증 정보가 포함되어 있는가

응답 body 확인해보기

API는 호출되지만 응답이 예상과 다를 수도 있다.

curl -i 'https://example.com/api/items?page=1'

curl로 직접 API를 호출해서 응답을 본다. 로컬 환경과 배포 환경에서 응답이 다른지 확인한다.

두 번째 단서: 요청 파라미터

API 호출은 되지만 파라미터가 잘못 전달될 수도 있다. 로컬에서는 기본값이 있어서 작동하지만, 배포에서는 그렇지 않을 수 있다.

확인 순서를 고정해두기

API 주변 문제가 반복된다면 확인 순서를 고정해두는 편이 낫다. 매번 감으로 접근하면 같은 실수를 반복하게 된다.

1. 배포 환경의 환경변수 확인
2. 로컬과 배포의 요청 비교
3. 응답 코드와 body 비교
4. 로그에서 에러 메시지 확인

응답 body를 수정 후 다시 확인하기

요청 방식이나 환경변수를 수정했다면, 바로 배포를 다시 하지 말고 다음을 먼저 확인한다.

1. 로컬에서 수정 내용이 정상 작동하는가
2. 배포 환경의 환경변수가 정말 업데이트되었는가
3. 이전 설정이 캐시되어 있지 않은가

한 번에 여러 설정을 바꾸지 않기

연동 메모 기준에서는 한 번에 여러 설정을 바꾸지 않는 것만으로도 원인 추적이 쉬워진다.

1. 한 가지 설정 수정
2. 배포
3. 실제 앱에서 테스트
4. 로그 확인
5. 결과를 기록

이 과정을 반복하면서 문제를 찾아간다. 관련 기록을 짧게라도 남겨두면 다음 확인이 훨씬 빨라진다.