API 연동이 실패하는 경우는 대부분 같은 이유입니다

① 같은 것을 두 번 처리합니다

네트워크가 끊겼다 붙으면 같은 요청이 두 번 갑니다. 받는 쪽이 이를 구분하지 못하면 주문이 두 건 생기거나 재고가 두 번 빠집니다.

• 요청마다 고유 키를 붙이고, 같은 키가 다시 오면 이전 결과를 그대로 돌려줍니다.
• 주문번호처럼 자연스러운 고유값이 있다면 그것을 기준으로 중복을 막습니다.
• "이미 처리됨"을 오류가 아니라 정상 응답으로 다루면 재시도 로직이 단순해집니다.

② 순서가 뒤집힙니다

"결제완료"와 "배송중"이 거의 동시에 발생하면 도착 순서가 바뀔 수 있습니다. 나중에 온 오래된 상태가 최신 상태를 덮어쓰면 화면이 거꾸로 갑니다.

해결은 간단합니다. 상태마다 발생 시각이나 순번을 함께 받고, 지금 저장된 것보다 오래된 것이면 무시합니다. 상태 값만 보고 덮어쓰는 구조는 반드시 사고가 납니다.

③ 실패를 조용히 넘깁니다

가장 위험한 형태입니다. 오류가 났는데 화면에는 아무 표시가 없고, 로그에만 남아 아무도 보지 않습니다. 며칠 뒤 "왜 이 주문만 안 넘어왔지"로 발견됩니다.

1. 실패를 데이터로 남깁니다실패한 요청을 목록으로 쌓아 화면에서 볼 수 있게 합니다. 로그 파일만으로는 아무도 보지 않습니다.
2. 재시도 규칙을 둡니다간격을 늘려 가며 몇 회까지 다시 시도할지 정하고, 그 뒤에는 사람이 처리하도록 넘깁니다.
3. 지연을 감시합니다평소 1분이면 오던 것이 30분째 안 오면 알림이 가야 합니다. 오류가 없어도 멈춰 있을 수 있습니다.
4. 수동 재처리 경로를 만듭니다담당자가 화면에서 다시 보낼 수 있어야 합니다. 개발자에게 요청해야만 처리되는 구조는 오래 못 갑니다.

④ 상대가 바뀝니다

연동 상대의 API 는 예고 없이 바뀝니다. 필드가 추가되거나, 값의 형식이 달라지거나, 응답이 느려집니다. 우리 쪽이 모르는 필드가 오면 멈추도록 만들어져 있으면 그날 연동이 통째로 죽습니다.

• 모르는 필드는 무시하고 넘어가도록 만듭니다.
• 필수로 쓰는 필드가 비어 있을 때의 동작을 정의해 둡니다.
• 응답이 느려질 때를 대비해 대기 시간 상한을 둡니다.
• 변경 공지를 받을 채널을 확보하고 담당자를 지정합니다.

연동은 만들고 끝나지 않습니다

채널 연동을 시작하기 전 확인 목록은 판매채널 연동 글에 정리해 두었습니다.