실시간 추적 요청이 시간 초과되었나요? 따라야 할 재시도, 폴백 및 상태 규칙
실시간 추적 요청이 시간 초과되면 배송물의 최신 상태를 지연, 분실 또는 변경 없음이 아닌 알 수 없음으로 처리하세요. 제한된 시간 예산 내에서만 재시도한 다음, 명확하게 표시된 마지막으로 확인된 업데이트를 보여 주거나 나중에 다시 확인하도록 사용자에게 요청하세요. 전체 과정에서 요청 결과, 데이터의 최신성, 소포의 실제 상태를 서로 분리해 유지하세요.

이러한 구분은 고객에게 표시되는 추적 페이지와 추적 데이터를 사용해 알림 또는 지원 워크플로를 트리거하는 시스템 모두에 중요합니다. 시간 초과는 제때 응답이 도착하지 않았다는 뜻입니다. 운송업체에 새로운 이벤트가 있는지, 상위 서비스가 요청을 처리했는지, 소포가 이동했는지는 알려 주지 않습니다.
먼저 시간 초과가 발생한 대상을 확인하세요
추적 요청은 여러 지점에서 실패할 수 있습니다. 브라우저가 애플리케이션을 기다리는 것을 중단했을 수도 있고, 애플리케이션이 추적 API를 기다리는 것을 중단했을 수도 있으며, 해당 API가 다른 서비스에 연결하는 동안 시간 초과가 발생했을 수도 있습니다. 사용자는 각각의 경우에 동일한 일반 오류를 볼 수 있지만, 적절한 다음 조치는 서로 다릅니다.
- 클라이언트 측 시간 초과: 앱이 기다리는 것을 중단했습니다. 서버 측 요청은 여전히 완료되었을 수 있습니다. 중복 작업을 일으킬 수 있는 다른 요청을 보내기 전에 자체 요청 로그 또는 결과 저장소를 확인하세요.
- 네트워크 또는 연결 실패: 시스템이 사용할 수 있는 응답을 받지 못했습니다. 원격 서비스가 요청을 처리했는지는 알 수 없을 수 있습니다.
- HTTP 504: 게이트웨이 또는 프록시가 상위 서버로부터 제때 응답을 받지 못했습니다. 이는 요청 경로를 설명하는 것이지 배송물을 설명하는 것이 아닙니다.
- HTTP 408: 서버가 기다리도록 준비된 시간 내에 완전한 요청 메시지를 받지 못했습니다. 이는 운송업체 추적 상태가 아닙니다.
- 오래된 이벤트가 포함된 HTTP 200: 요청은 성공했지만 반환된 추적 정보는 여전히 오래된 것일 수 있습니다. 성공적인 HTTP 응답이 최신성을 보장하지는 않습니다.
이러한 결과를 요청 진단 정보로 기록하세요. 어느 것도 “운송 중”, “예외” 또는 “배달 완료”와 같은 배송물 라벨로 변환하지 마세요. 이러한 라벨은 전송 계층이 아니라 추적 이벤트 또는 문서화된 상태 필드에서 가져와야 합니다.
무제한 루프가 아닌 제한된 재시도를 사용하세요
읽기 전용 추적 조회의 경우 시간 초과 후 재시도하는 것이 합리적인 경우가 많습니다. 그래도 제한해야 합니다. 반복 요청은 문제가 있는 서비스의 부하를 증가시키고, 사용자의 대기 시간을 늘리며, 여러 애플리케이션 계층이 독립적으로 재시도할 때 중복 작업을 만들 수 있습니다.
- 전체 기한을 설정하세요. 최초 시도와 모든 재시도를 포함해 사용자에게 표시되는 작업이 얼마나 오래 걸릴 수 있는지 결정하세요. 호출자가 기다릴 수 있는 시간을 초과하는 새롭고 전체적인 기한을 각 시도에 부여하지 마세요.
- 작업을 반복해도 안전한지 확인하세요. 조회는 일반적으로 배송물을 등록하거나 설정을 변경하거나 리소스를 생성하는 요청과 다릅니다. 제공업체의 계약 또는 멱등성 제어가 안전성을 보장하지 않는 한 상태를 변경하는 요청을 자동으로 재생하지 마세요.
- 일시적인 실패는 신중하게 재시도하세요. 작고 명시적인 재시도 예산과 지터가 포함된 지연을 사용하고, 여러 클라이언트에서 동시에 즉시 재시도하지 마세요.
- 적용 가능한 서버 지침을 준수하세요. 응답에 유효한
Retry-After헤더가 포함되어 있으면 그보다 이른 재시도를 예약하지 마세요. 더 엄격한 애플리케이션 또는 제공업체별 제한도 준수하세요. - 기한 또는 예산이 소진되면 중지하세요. 대체 응답으로 전환하고 워크플로에 필요한 경우 나중에 별도로 조정 작업을 예약하세요.
실용적인 설계에서는 남은 시간이 충분한 경우 사용자에게 표시되는 재시도를 한 번 허용하고, 추가 시도는 백그라운드 새로 고침으로 전환할 수 있습니다. 이는 정책의 한 예일 뿐 보편적인 API 규칙은 아닙니다. 서비스 수준 목표, 관찰된 지연 시간, 제공업체 문서에 따라 제한을 선택하세요. 또한 HTTP 라이브러리, 게이트웨이 및 작업 워커가 수행하는 재시도도 계산하세요. 그렇지 않으면 적당해 보이는 애플리케이션 정책이 많은 상위 호출을 만들어 낼 수 있습니다.
HTTP 429의 경우 응답을 즉시 재시도할 이유가 아니라 속도 제한 신호로 처리하세요. HTTP 503은 요청을 일시적으로 처리할 수 없음을 나타낼 수 있으며, 서버가 Retry-After를 제공할 수도 있습니다. 504는 일시적일 수 있지만 다음 시도가 성공한다고 보장하지는 않습니다. 인증 오류는 일반적으로 자격 증명 또는 권한 확인이 필요하고, 잘못된 요청은 입력 수정이 필요합니다. “찾을 수 없음” 결과를 반환하는 추적 식별자는 더 신중하게 처리해야 합니다. 제공업체의 문서화된 동작과 배송물의 단계에 따라 기록을 찾기에는 너무 이른 것일 수도 있고 식별자가 잘못되었을 수도 있습니다. 그러한 결과 하나만으로 소포가 존재하지 않는다고 단정하지 마세요.
알고 있는 정보를 보존하는 대체 방안을 선택하세요
가장 안전한 대체 방안은 일반적으로 마지막으로 확인된 추적 결과에 자체 이벤트 시간과 정직한 최신성 라벨을 함께 표시하는 것입니다. 해당 결과를 현재 요청 실패와 구분하세요. 페이지에는 “사용 가능한 최신 업데이트: 시설에서 출발했습니다. 마지막 확인: [시간]. 최신 업데이트를 일시적으로 사용할 수 없습니다.”라고 표시할 수 있습니다. 시스템이 실제로 기록한 경우에만 “마지막 확인”을 포함하세요. 이는 운송업체 이벤트 시간을 대신하지 않습니다.
지원할 수 있는 가장 구체적인 시간을 사용하세요. 운송업체 이벤트 시간은 이벤트가 발생했다고 보고된 시점을 나타냅니다. 시스템이 해당 이벤트를 수신한 시간은 수집 시점을 나타냅니다. 사용자가 페이지를 연 시간은 어느 쪽도 나타내지 않습니다. 출처에서 신뢰할 수 있는 이벤트 시간 또는 시간대를 제공하지 않는다면 임의로 만들지 마세요. 마찬가지로 캐시된 결과에 검색 시간이 기록되어 있지 않다면 최근에 새로 고침되었다고 주장하지 말고 “마지막으로 사용 가능한 업데이트”라고 부르세요.
대체 방안은 다음 세 가지 경계를 따라야 합니다.
- 캐시된 데이터는 캐시된 데이터로 표시하세요. 오래된 이벤트를 시간 초과 요청의 결과로 표시하지 마세요.
- 경과 시간으로 진행 상황을 추론하지 마세요. 소포가 며칠 동안 운송 중이었다는 이유만으로 “배달을 위해 출발”한 것은 아닙니다.
- 중요한 불확실성을 숨기지 마세요. 이전 결과가 없다면 조작된 기본 상태를 표시하지 말고 추적을 일시적으로 사용할 수 없다고 말하세요.
그 밖의 대체 경로로는 이전에 동기화된 추적 저장소, 승인된 운송업체 조회 또는 이후의 백그라운드 새로 고침이 있을 수 있습니다. 배송물, 권한 및 데이터 소스의 약관에 부합하는 경우에만 사용하세요. 두 번째 소스는 이벤트 이름이나 보고 지연 시간이 다를 수 있으므로 출처를 보존하고, 이를 처리할 규칙 없이 충돌하는 기록을 병합하지 마세요. 고객이 결과를 바탕으로 조치할 수 있다면 스피너를 무기한 표시하는 대신 재시도하거나 지원팀에 문의할 방법을 제공하세요.
요청 상태, 데이터 최신성 및 배송물 상태를 분리하세요
사용자 인터페이스에서 함께 표시하더라도 이는 서로 다른 세 필드입니다. 요청 상태는 조회가 성공했는지, 시간 초과되었는지 또는 오류를 받았는지를 나타냅니다. 데이터 최신성은 반환되거나 저장된 정보가 언제 관찰되었는지를 나타냅니다. 배송물 상태는 추적 소스가 소포에 대해 보고하는 내용을 나타냅니다. 이를 분리하면 일시적인 API 실패가 유효한 배송 이벤트를 덮어쓰거나 오래된 운송 중 이벤트가 현재 상태라는 주장을 하게 되는 것을 방지할 수 있습니다.
예를 들어 시스템은 이전 조회에서 확인된 “배달 완료” 이벤트를 보유하고 있는 동안 현재 새로 고침이 시간 초과될 수 있습니다. 배송 이벤트가 사라지는 것은 아닙니다. 올바른 결합 상태는 마지막으로 사용 가능한 배송물 상태가 배달 완료이고 최신 새로 고침은 실패했다는 것입니다. 반대로 마지막 이벤트가 “운송 중”이라면 시간 초과는 소포가 현재도 운송 중임을 확인하지 않습니다. 최신 응답을 얻지 못했다는 것만 확인합니다.
이벤트가 순서가 뒤바뀌어 도착할 때는 정의된 규칙을 적용하세요. 가능한 경우 이벤트 식별자, 타임스탬프, 출처 및 제공업체의 문서화된 상태 의미를 비교하세요. 시스템이 업데이트를 받은 순서가 배송 이벤트가 발생한 순서라고 가정하지 마세요. 늦게 도착한 오래된 이벤트가 자동으로 더 최신인 확인 상태를 대체해서도 안 됩니다. 그러나 정정 및 예외가 정당할 수 있으므로 배달 후 상태 변경이 불가능하다고 간주하는 일률적인 규칙은 피하세요. 기본 이벤트를 보존하고 기록을 조용히 다시 쓰지 말고 모순을 조사하세요.
제공업체가 HTTP 202를 반환하면 해당 엔드포인트의 계약에 따라 해석하세요. 요청이 수락되었다는 사실만으로 추적 조회가 완료된 것은 아닙니다. 마찬가지로 HTTP 200은 해당 엔드포인트의 의미에 따라 HTTP 요청이 성공했음을 나타낼 뿐이며, 모든 추적 필드가 존재하거나 최신 상태임을 증명하지는 않습니다. 제공업체 문서를 확인한 후에만 제공업체별 응답 필드를 매핑하세요.
고객을 불안하게 만들지 않으면서 운영자에게 실패를 표시하세요
유용한 운영 기록에는 요청 ID, 엔드포인트 또는 작업, 시도 횟수, 경과 시간, 시간 초과 계층, 수신한 경우 HTTP 상태, 응답이 실시간 조회에서 왔는지 대체 경로에서 왔는지가 포함됩니다. 추적 데이터의 경우 출처와 관련 이벤트 또는 검색 타임스탬프를 기록하세요. 추적 번호와 고객 정보는 조직의 접근 및 보존 규칙에 따라 처리하세요. 진단에 유용하다는 이유로 제한 없는 로그에 전체 식별자를 노출해서는 안 됩니다.
단일 시간 초과에 의존하지 말고 패턴을 관찰하세요. 한 운송업체 경로의 시간 초과율 증가, 반복되는 429 응답 또는 운송업체 이벤트 시간과 검색 시간 사이의 격차 확대는 서로 다른 문제를 가리킬 수 있습니다. 첫 번째는 제공업체 조사가 필요할 수 있고, 두 번째는 속도 제어가 필요할 수 있으며, 세 번째는 동기화 또는 이벤트 전달 확인이 필요할 수 있습니다. 17TRACK Tracking API와 같은 제공업체를 통해 애플리케이션이 추적 기능을 제공한다면, 이러한 일반 규칙을 구현하기 전에 해당 제공업체의 문서에서 엔드포인트별 응답 필드, 요청 제한 및 오류 처리를 확인하세요.
고객에게 표시되는 메시지는 정확하고 절제되게 작성하세요. “현재 추적 정보를 새로 고칠 수 없습니다. 다음은 사용 가능한 최신 업데이트입니다.” 배송물이 판매자 또는 운송업체가 제공한 예상 배송 기간을 초과한 경우 나중에 다시 확인하거나 지원팀에 문의하는 등 도움이 되는 다음 단계를 제공하세요. 시스템이 보장할 수 없는 새로 고침 시간을 약속하지 마세요.
시간 초과에 안전한 추적 흐름을 위한 출시 체크리스트
- 각 시간 초과를 어느 계층이 적용하고 재시도를 어느 계층이 담당하는지 확인합니다.
- 전체 요청 기한과 별도의 제한된 재시도 예산을 설정합니다.
- 자동으로 재시도되는 작업을 반복해도 안전한지 확인합니다.
- 속도 제한과 유효한
Retry-After지침을 준수합니다. - 요청 결과를 배송물 상태 및 이벤트 기록과 별도로 저장합니다.
- 대체 데이터를 라벨링하고 가능한 경우 출처와 타임스탬프를 보존합니다.
- 캐시 없음, 오래된 캐시, 429, 503, 504 및 늦은 응답 시나리오를 테스트합니다.
- 시간 초과가 잘못된 배송 알림을 트리거하거나 확인된 이벤트를 삭제하지 못하는지 확인합니다.
기본 원칙은 간단합니다. 안전하고 유용한 경우에만 요청을 재시도하고, 식별할 수 있는 정보로만 대체하며, HTTP 시간 초과를 근거로 배송물 상태를 절대 주장하지 마세요.
FAQ
시간 초과된 추적 요청을 즉시 재시도해야 하나요?
자동으로 재시도해서는 안 됩니다. 작업을 반복해도 안전한지, 전체 기한에 다른 시도를 위한 시간이 남아 있는지, 속도 제한 지침에서 대기하도록 요구하지 않는지 확인하세요. 읽기 전용 조회에는 짧고 제한된 지터 재시도가 적절할 수 있지만, 반복적인 즉시 재시도는 좋은 기본값이 아닙니다.
HTTP 504는 운송업체의 추적 시스템이 중단되었다는 뜻인가요?
아닙니다. 게이트웨이 또는 프록시가 상위 서비스로부터 제때 응답을 받지 못했다는 뜻입니다. 문제는 해당 요청 경로의 어느 곳에서나 발생할 수 있습니다. 운송업체의 전반적인 가용성이나 소포의 상태를 확정하는 것은 아닙니다.
시간 초과 후 마지막으로 알려진 상태를 표시할 수 있나요?
예. 성공적인 실시간 새로 고침이 아니라 사용 가능한 최신 정보라고 라벨링한다면 가능합니다. 알고 있는 경우 이벤트 시간과 검색 시간을 표시하고, 더 최신인 업데이트를 확인할 수 없었다는 점을 명확히 하세요.
시간 초과가 배송물 상태를 “운송 중”에서 “예외”로 변경해야 하나요?
아닙니다. 시간 초과는 요청 실패이지 배송 이벤트가 아닙니다. 신뢰할 수 있는 추적 소스가 변경을 뒷받침하는 이벤트 또는 상태를 제공할 때만 배송물 상태를 변경하세요.
시간 초과된 요청이 추적 기록을 생성하거나 등록하는 작업이었다면 어떻게 해야 하나요?
실패했다고 가정하지 마세요. 응답이 손실되기 전에 원격 시스템이 이를 처리했을 수 있습니다. 다시 제출하기 전에 기존 결과를 확인하고 문서화된 멱등성 메커니즘 또는 제공업체가 승인한 복구 절차를 사용하세요.
출처
- RFC 9110, HTTP Semantics — HTTP 상태 정의,
Retry-After및 요청 재시도 시 고려 사항. - RFC 6585, Additional HTTP Status Codes — HTTP 429의 정의와
Retry-After와 함께 사용하는 방법. - Amazon Builders’ Library, “Timeouts, retries, and backoff with jitter” — 재시도 증폭, 백오프 및 지터에 관한 엔지니어링 지침.
- 17TRACK Tracking API documentation — 구현 전에 제공업체별 API 동작을 확인하기 위한 참고 자료.


