Tracking API 오류 처리: 잘못된 운송장 번호, 요청 제한 및 재시도 관리 방법

잘못된 입력, 일시적 장애, 요청 제한, 배송 상태 결과를 분리하여 추적 API 오류를 처리하세요. 잘못된 추적 번호는 변경 없이 재시도하지 말고 거부하거나 수정하며, 요청이 제한될 때는 요청량을 조정하고, 제한된 지수 백오프와 지터를 사용하여 일시적 장애를 재시도하세요. 등록 또는 기타 쓰기 요청을 반복하기 전에 첫 번째 시도가 성공했는지 확인하세요.

주문 관리 시스템, 창고 플랫폼 또는 고객용 추적 페이지에 추적 데이터를 연결하는 개발자에게 목표는 단순히 실패한 요청을 줄이는 것이 아닙니다. 중복 등록, 재시도 폭주, 오해를 불러일으키는 배송 메시지 또는 불필요한 지원 요청 없이 신뢰할 수 있는 배송 가시성을 제공하는 것입니다.

응답을 선택하기 전에 실패를 분류하세요

추적 통합에서는 네 가지 별도 결과를 평가해야 합니다. 네트워크 요청이 완료되었는지, API가 작업을 수락했는지, 요청한 각 추적 항목이 성공했는지, 배송 이벤트를 이용할 수 있는지입니다. 이 네 가지를 하나의 성공 또는 실패 플래그로 처리하면 피할 수 있는 오류가 발생합니다.

HTTP 성공 응답이 반환되었다고 해서 배치의 모든 항목이 성공한 것은 아닙니다. 반대로 추적 이벤트 없이 조회가 성공적으로 처리되었다고 해서 반드시 API 오류인 것도 아닙니다. 응답 본문을 확인하고 각 결과에 대해 제공업체가 문서화한 의미를 적용하세요.

조건	권장 조치	변경 없이 재시도?
형식이 잘못된 번호 또는 잘못된 요청 필드	입력을 검증하고 수정	아니요
자격 증명 누락 또는 유효하지 않음	자격 증명, 권한 및 환경 확인	수정할 때까지 안 함
요청 제한 응답	영향받은 작업을 지연하고 공유 요청 부담을 줄임	필요한 대기 후 안전한 경우
일시적인 서비스 장애	제한된 백오프를 적용하고 작업의 안전성을 확인	일반적으로 재시도 예산 내에서
등록 제출 후 시간 초과	등록이 존재하는지 조정하여 확인	무조건 재시도하지 않음
배송 이벤트가 없는 수락된 조회	문서화된 추적 수명 주기를 따름	빠른 재시도가 아닌 예약된 새로 고침 사용

HTTP 상태 코드는 시작점일 뿐, 제공업체별 의사 결정 트리 전체를 제공하지는 않습니다. RFC 9110은 HTTP 의미를 정의하고, RFC 6585는 429 Too Many Requests를 정의합니다. 통합에서는 문서화된 애플리케이션 오류 코드와 항목 수준 결과도 해석해야 합니다.

잘못된 추적 번호: 잘못된 입력과 누락된 이벤트를 구분하세요

“잘못된 추적 번호”는 형식이 잘못된 식별자, 지원되지 않는 운송업체 및 번호 조합, 필수 운송업체 필드 누락 또는 제공업체별 기타 검증 실패 등 서로 다른 문제를 의미할 수 있습니다. 추적 이벤트가 반환되지 않았다는 이유만으로 번호가 잘못되었다고 판단하지 마세요.

식별자를 손상시키지 않고 검증하기

• 추적 번호를 문자열로 저장하세요. 숫자로 저장하면 앞의 0이 제거되거나 긴 식별자가 변경될 수 있습니다.
• 원래 입력을 보존하세요. 변환 과정을 감사할 수 있도록 별도의 정규화된 값을 유지하세요.
• 보수적으로 정규화하세요. 적절한 경우 앞뒤 공백을 제거하되, 문서화된 규칙에서 허용하는 경우에만 내부 문자를 제거하거나 대소문자를 변경하세요.
• 필수 필드를 로컬에서 확인하세요. 전송하기 전에 빈 번호, 누락된 운송업체 식별자 및 잘못된 요청 형식을 감지하세요.
• 범용 추적 번호 정규식을 사용하지 마세요. 한 운송업체를 위해 만든 규칙이 다른 운송업체의 유효한 식별자를 거부할 수 있습니다.
• 필드에 무엇이 포함되어 있는지 확인하세요. 엔드포인트가 명시적으로 지원하지 않는 한 주문 번호, 창고 참조 번호 및 운송업체 추적 번호는 서로 바꿔 사용할 수 없습니다.

API가 입력을 명시적으로 거부하면 자동 재시도 루프가 아니라 수정 절차로 보내세요. 모든 검증 문제를 “추적 실패”로 축약하지 말고 “운송업체 식별자 필요”와 같은 유용한 이유를 포함하세요.

“이벤트 없음”을 별도 상태로 처리하세요

유용한 이동 이벤트가 제공되기 전에 배송에 추적 식별자가 먼저 부여될 수 있습니다. 올바른 대응은 API의 문서화된 상태 모델과 배송 상황에 따라 달라집니다. 식별자가 배송 시스템에서 생성되었는지, 운송업체 선택이 올바른지, 응답이 거부된 입력이 아니라 데이터 대기 중임을 나타내는지 확인하세요.

input_rejected, awaiting_events, temporarily_unavailable와 같은 서로 다른 내부 상태를 사용하세요. 이는 제안된 애플리케이션 상태이며 표준화된 API 값이 아닙니다. 이러한 상태를 사용하면 일시적인 데이터 공백이 부정확한 고객 메시지로 이어지는 것을 방지할 수 있습니다.

작업자별이 아니라 통합 전체에서 요청 제한을 관리하세요

RFC 6585는 HTTP 429를 요청 제한 응답으로 정의하며 Retry-After 헤더를 포함할 수 있도록 합니다. 이 표준은 모든 추적 API에 적용되는 보편적인 허용량이나 계산 방법을 정하지 않습니다. 제한은 계정, 자격 증명, 엔드포인트 또는 다른 범위에 따라 문서화될 수 있으므로 제공업체의 실제 규칙을 사용하세요.

RFC 9110은 Retry-After에 대해 음이 아닌 초 단위 숫자 또는 HTTP 날짜라는 두 가지 형식을 지정합니다. 두 형식을 모두 구문 분석하세요. 값이 날짜인 경우 남은 대기 시간을 신중하게 계산하고 시계 차이를 고려하세요. 값이 없거나 사용할 수 없다면 구성된 대체 백오프 정책을 적용하세요.

다른 작업자가 동일한 허용량을 계속 사용하는 상황에서 한 작업자가 독립적으로 대기하는 것만으로는 충분하지 않습니다. 관련 자격 증명 또는 계정의 공유 경계에서 요청을 제어하세요. 중앙 스케줄러, 공유 토큰 버킷 또는 이에 상응하는 분산 제어를 사용하여 트래픽을 조정할 수 있습니다.

1. 영향받은 범위를 식별하세요. 제한이 적용되는 엔드포인트, 자격 증명 또는 계정을 확인하세요.
2. 서버의 대기 지시를 따르세요. 유효한 Retry-After 값이 허용하는 시간보다 이른 재시도를 예약하지 마세요.
3. 대기 중인 영향을 받은 작업을 지연하세요. 제한이 실제로 독립적이라면 관련 없는 트래픽까지 차단하지 마세요.
4. 동시성 또는 요청 빈도를 줄이세요. 요청 패턴을 변경하지 않고 한 번 대기하기만 하면 같은 문제가 다시 발생할 수 있습니다.
5. 간격을 두고 재개하세요. 대기 시간이 끝났을 때 전체 백로그를 동시에 실행하지 마세요.

지원되는 경우 배치 처리를 사용하면 요청 수를 줄일 수 있지만, 문서화된 배치 크기 및 계산 규칙을 따라야 합니다. 하나의 배치가 허용량 한 단위를 소비한다고 가정하지 마세요. 또한 가능한 경우 웹훅을 사용하여 불필요한 폴링을 줄이되, 통합에 필요한 조정 프로세스는 유지하세요.

백오프와 지터를 사용하여 제한된 횟수로 재시도하세요

요청을 변경하지 않아도 장애가 해소될 수 있고 작업을 반복해도 안전한 경우 재시도가 적절합니다. 일시적인 연결 장애와 일부 서버 오류가 이 범주에 포함될 수 있습니다. 형식이 잘못된 페이로드, 유효하지 않은 자격 증명 또는 영구적인 권한 문제는 일반적으로 먼저 수정해야 합니다.

실용적인 대체 방법은 최대 한도가 있는 지수 백오프와 전체 지터입니다.

backoff_window = min(max_delay, base_delay * 2^retry_index)
jitter_delay = random(0, backoff_window)
next_delay = max(valid_retry_after_delay, jitter_delay)

여기서 retry_index는 첫 번째 재시도에서 0으로 시작하며, Retry-After가 없으면 추가적인 최소 대기 시간이 적용되지 않습니다. 이는 구현상의 선택이며 필수 HTTP 알고리즘은 아닙니다. 작업량과 제공업체의 지침에 따라 기본 지연 시간, 최대 한도, 시도 횟수 제한 및 전체 기한을 정하세요.

지터는 모든 작업자가 같은 일정에 재시도하는 대신 요청을 시간에 분산합니다. 지연 한도는 지수 구성 요소를 제한하지만, 서버가 요청한 더 긴 유효 대기 시간을 무시해서는 안 됩니다. 해당 대기 시간이 작업 기한을 초과하면 일찍 재시도하지 말고 정책에 따라 작업을 연기하거나 종료하세요.

모든 재시도 체인에 종료 지점을 설정하세요

• 시도 횟수 제한: 추가 요청 수를 제한하세요.
• 경과 시간 제한: 유용한 처리 시간을 초과한 작업은 재시도를 중지하세요.
• 명확한 책임 주체: 재시도를 제어하는 계층을 정하여 HTTP 클라이언트 재시도와 큐 재시도가 예기치 않게 중복되지 않도록 하세요.
• 지속 가능한 예약: 수명이 짧은 프로세스에서 장시간 대기하는 대신 지연된 작업을 저장하세요.
• 복구 경로: 이유와 다음 작업을 포함하여 소진된 작업을 검토 가능한 실패 작업 큐로 보내세요.

장애가 지속되는 동안에는 회로 차단기를 사용하여 일반 호출을 일시적으로 중지하고 제어된 복구 확인만 허용하는 방안을 고려하세요. 이는 애플리케이션 복원력 패턴이며, 특정 추적 제공업체가 이를 요구한다는 증거는 아닙니다.

다시 전송하기 전에 모호한 쓰기 작업을 해결하세요

시간 초과는 애플리케이션이 완전한 응답을 받지 못했다는 뜻입니다. 서버가 요청을 거부했거나 처리하지 않았다는 뜻은 아닙니다. 추적 번호를 등록하거나 추적 설정을 변경할 때 이 구분이 중요합니다.

RFC 9110은 멱등 메서드를 설명하며, 반복이 안전하거나 원래 작업이 적용되지 않았음을 알 수 있는 근거 없이 멱등성이 없는 요청을 자동으로 재시도하지 않도록 주의를 줍니다. 모든 추적 엔드포인트가 읽기 전용 조회처럼 동작한다고 가정하지 말고 문서화된 작업 의미를 평가하세요.

• 제공되는 경우 제공업체가 문서화한 멱등성 메커니즘을 사용하고 해당 범위와 보존 규칙을 따르세요.
• 동일한 논리 작업을 재시도할 때는 동일한 멱등성 키를 사용하세요. 임의의 사용자 지정 헤더가 적용될 것이라고 가정하지 마세요.
• 지원되는 경우 모호한 쓰기를 반복하기 전에 기존 등록을 확인하세요.
• 제공업체가 문서화한 배송 식별성에 맞춰 로컬 고유성 제약 조건을 사용하세요.
• 작업 결과를 저장하여 큐 재전달이 자동으로 또 다른 쓰기 작업을 실행하지 않도록 하세요.

배치 작업의 경우 각 항목의 결과를 저장하세요. 일시적으로 실패한 것으로 분류된 항목만 재시도하고, 결과가 계속 불명확한 항목은 조정하여 확인하세요. 전체 배치를 다시 실행하면 성공한 작업이 반복되고 요청 허용량이 불필요하게 소비될 수 있습니다.

추적 제공업체에 정책을 적용하세요

17TRACK 통합의 경우 제공업체별 계약을 확인하기 위한 출발점으로 Tracking API 페이지와 공식 API 문서를 사용하세요. 일반적인 HTTP 가이드의 가정을 하드코딩하지 말고 오류 분류기를 구성 가능하게 유지하세요.

구현 전에 관련 엔드포인트의 요청 스키마, 응답 봉투, 항목 수준 오류의 의미, 요청 제한 범위, 배치 제약 조건 및 중복 제출 규칙을 확인하세요. 이벤트 전달을 사용하는 경우 승인, 인증 및 재전달 요구 사항도 확인하세요. 이 가이드는 17TRACK의 수치상 요청 제한, 재시도 일정 또는 멱등성 기능을 규정하지 않습니다.

확인된 각 규칙을 제공업체 응답에서 애플리케이션 작업으로 매핑하여 기록하세요. 즉 입력 수정, 구성 복구, 대기, 조정 또는 에스컬레이션입니다. 인식되지 않은 오류는 진단 맥락을 보존하고 제한된 대체 경로를 따라야 하며, 무제한 재시도를 기본값으로 사용해서는 안 됩니다.

복구 품질을 모니터링하고 실패 경로를 테스트하세요

작업, 엔드포인트, HTTP 상태, 애플리케이션 오류 코드, 시도 횟수, 지연 시간, 다음 예약 작업 및 제공되는 경우 제공업체 요청 식별자를 기록하세요. API 키, 불필요한 주소 정보 또는 제한 없는 응답 본문은 기록하지 마세요. 전체 값이 필요하지 않은 경우 추적 식별자를 마스킹하거나 해시하세요.

잘못된 입력 비율, 요청 제한, 큐 대기 시간, 소진된 재시도 및 마지막 성공 동기화를 별도로 추적하세요. 통합의 HTTP 오류율이 낮더라도 오래된 배송 정보를 제공할 수 있습니다. 고객용 페이지는 마지막으로 알려진 배송 상태를 유지하고 새로 고침 실패와 운송업체가 보고한 배송 예외를 구분해야 합니다.

출시 전에 잘못된 입력, 이벤트가 없는 유효한 식별자, 두 가지 형식의 Retry-After, 누락된 헤더, 부분 배치 실패, 쓰기 후 시간 초과 및 큐 재전달을 테스트하세요. 또한 재시도 예산이 소진될 만큼 긴 장애를 시뮬레이션하세요. 작업이 예측 가능하게 중지되거나 연기되고, 성공한 항목이 불필요하게 다시 실행되지 않으며, 실패한 항목을 복구할 수 있을 때만 테스트를 통과한 것으로 간주하세요.

FAQ

잘못된 추적 번호를 자동으로 재시도해야 하나요?

API가 입력을 잘못된 것으로 명시적으로 거부한 경우에는 재시도하지 마세요. 먼저 번호, 운송업체 선택 또는 필수 필드를 수정하세요. 반대로 응답이 배송 이벤트를 아직 이용할 수 없다는 의미라면 검증 실패로 처리하지 말고 문서화된 새로 고침 절차를 사용하세요.

HTTP 200이면 배치 요청이 완전히 성공했다는 뜻인가요?

반드시 그렇지는 않습니다. 작업 수준 및 항목 수준 결과에 대한 제공업체의 응답 스키마를 확인하세요. 성공한 항목은 저장하고 실패한 항목을 분리하여 한 항목을 재시도할 때 나머지 항목이 불필요하게 반복되지 않도록 하세요.

추적 통합에서 몇 번까지 재시도해야 하나요?

보편적인 횟수는 없습니다. 제공업체의 지침, 작업의 안전성 및 결과가 유용하게 유지되는 기간을 기준으로 시도 횟수 제한과 경과 시간 예산을 모두 설정하세요. 예약된 백그라운드 동기화는 대화형 고객 요청과 다른 복구 시간을 허용할 수 있습니다.

시간 초과가 발생하면 배송을 즉시 실패로 표시해야 하나요?

아니요. 요청 시간 초과는 통합의 결과이지 배송 이벤트가 아닙니다. 마지막으로 알려진 추적 상태를 보존하고 안전한 복구를 예약하며 연결 문제를 배송 실패 알림으로 변환하지 마세요.

재시도가 소진되면 어떻게 해야 하나요?

진단 맥락과 함께 작업을 지속 가능한 실패 작업 큐 또는 검토 큐로 이동하세요. 복구에 수정된 입력, 복구된 자격 증명, 제공업체 지원 또는 이후의 제어된 재실행 중 무엇이 필요한지 식별하세요. 조용히 삭제하거나 동일한 무제한 재시도 주기를 다시 시작하지 마세요.

출처

• RFC 9110: HTTP Semantics — HTTP 상태 의미, 멱등 메서드, 자동 재시도 고려 사항 및 Retry-After 필드.
• RFC 6585: Additional HTTP Status Codes — 429 Too Many Requests의 정의와 선택적 Retry-After 헤더.
• 17TRACK Tracking API — 추적 API 제품의 공식 진입점.
• 17TRACK API documentation — 제공업체별 통합 요구 사항을 확인하기 위한 참고 자료.