백링크 도구가 결과를 반환하지 않음: 오류 테이블

대부분의 경우를 포괄하는 규칙

네트워크 오류는 재시도하세요. 401 또는 402에는 재시도하지 마세요. 첫 번째는 몇 초 만에 해결되지만, 두 번째는 인간의 개입이 필요하며 무작정 재시도하면 로그만 가득 찹니다.

모든 JSON 응답에는 ok 필드가 포함되어 있으며, 인증된 응답에는 호출 비용과 남은 잔액을 나타내는 _credits 필드가 추가됩니다. HTTP 상태 코드가 정상적으로 보이더라도 본문에서 ok를 확인하세요.

아래의 재시도 간격은 공학적 조언이며 문서화된 제한 사항이 아닙니다. 우리가 보유한 API 문서에는 속도 제한(rate limit)이 명시되어 있지 않으므로 자체 상한선을 설정하고 적절히 유지하세요.

401과 402에 재시도를 사용하지 않는 이유

401은 키 문제이고 402는 잔액 문제입니다. 두 시도 사이에 1초의 간격이 있다면 둘 다 해결되지 않으므로 재시도는 로그에 노이즈만 추가할 뿐입니다.

대기한다고 해서 402가 해결되지도 않습니다. 잔액은 계정 페이지에서 충전하기 전까지 그대로 유지되므로, 유일한 대응책은 명확한 메시지 표시와 예산 담당자에게 알림을 보내는 것입니다.

401 오류는 헤더나 키 파라미터를 확인하고 키가 교체되지 않았는지 확인해야 합니다. 잘못된 키로 여러 번 재시도해도 아무런 도움이 되지 않습니다.

잘못된 키와 빈 잔액은 대시보드에서 서로 다르게 표시됩니다. 별도의 알림으로 구분하세요. 잔액 충전 담당자가 키 오타로 인해 깨어나지 않도록, 키 교체 담당자가 잔액 문제로 호출되지 않도록 하세요.

네트워크 오류 및 백오프(Backoff)

타임아웃이나 연결 재설정은 자체적으로 해결될 수 있으므로, 이러한 경우만 재시도할 가치가 있습니다. 1, 2, 4초 후에 재시도하고, 마지막 8초 전까지 약간의 지터(jitter)를 추가한 후 네 번째 시도 이후에는 중단하세요.

이 간격들은 권장 사항일 뿐 문서화된 제한이 아닙니다. 자체 상한선을 유지하고 모든 재시도를 로깅하세요. 재시도 빈도가 증가하면 일반적으로 상류 시스템의 문제 징후이므로 알림을 보내세요.

타임아웃은 명시적으로 named constant로 설정하세요. 라이브러리 업그레이드에 따라 변경되는 암묵적인 기본값은 야간 작업이 특정 머신에서만 실패하는 일반적인 원인입니다.

실패율뿐만 아니라 상류 시스템의 응답 시간도 모니터링하세요. 실패하지는 않지만 응답이 느린 경우에도 워커를 점유할 수 있으며, 재시도 루프는 이러한 지연을 악화시킬 수 있습니다.

호출 전 도메인 정규화

대부분의 호출 실패는 네트워크가 아닌 입력 창에서 시작됩니다. 사용자는 복사한 내용을 그대로 붙여넣으며, 코드는 이를 API가 인식할 수 있는 도메인 형태로 변환해야 합니다.

스키마와 경로 제거

스키마, 경로 및 쿼리 문자열을 제거합니다. 붙여넣은 기사 주소는 호스트로 변환되며, 오직 호스트만 상위로 전송됩니다.

호스트도 소문자로 변환합니다. 폼, 배치 작업, 테스트 모두에서 동일한 규칙이 적용되도록 정리 로직을 하나의 함수로 유지하세요.

끝점의 슬래시와 쿼리 문자열이 포함된 실제 붙여넣기 입력 5~6개로 정리 로직을 테스트하세요. 이러한 케이스는 깔끔한 예제에서는 발견되지 않는 버그를 드러냅니다.

www 처리 규칙을 하나로 결정

www. 처리 규칙을 하나 정해 단일 함수에 적용하세요. 그래야 동일한 사이트가 두 가지 표기로 조회되는 것을 방지할 수 있습니다.

함수 옆에 규칙을 명시하세요. 나중에 stray www를 마주하는 개발자는 두 번째 의견이 아닌 결정 사항을 찾을 수 있습니다.

어떤 규칙을 선택하든 해당 파일에 유지하고 테스트를 하나 작성하세요. 테스트는 결정의 기록이며 간결해야 합니다.

도메인이 될 수 없는 입력 거부

공백이 있거나 빈 라벨이 포함된 입력을 거부하고 폼에 짧은 메시지를 표시하세요. 거부된 문자열은 비용이 들지 않지만, 잘못된 입력은 호출 실패와 사용자 혼란을 초래합니다.

끝점의 점은 예외 케이스입니다. 호스트 끝의 점 하나를 제거하고 나머지는 유효하지 않은 것으로 처리하세요.

토스트 알림이 사라지지 않도록 필드 옆에 거부 메시지를 표시하세요. 사용자는 무엇이 잘못되었는지 확인하고 한 번에 수정할 수 있습니다.

빈 결과와 인덱스 갱신 시점

사용자가 폼에 'check my backlink'을 입력하고 결과가 없을 때, 빈 응답이 항상 오류는 아닙니다. 이는 도메인이 신규이거나 규모가 작거나 단순히 인덱스에 아직 포함되지 않았음을 의미할 수 있으며, 화면에 그 사실을 명시해야 합니다.

신규 사이트

지난 주에 출시된 사이트는 인덱스에 참조 도메인이 없을 수 있습니다. '아직 인덱싱되지 않음' 메시지와 함께 인덱스 날짜를 표시하고, 교차 확인을 위해 무료 overview 호출을 제안하세요.

빈 응답을 장시간 캐싱하지 마세요. 몇 시간이면 충분하며, 다음 인덱스 갱신 시 사이트가 포함될 수 있습니다.

인덱스가 마지막으로 갱신된 시점을plain language로 알려주세요. 빈 응답 옆의 날짜는 긴 설명보다 간극을 더 잘 설명합니다.

자체 UI에 한 줄 정도의 메모를 추가하는 것으로 충분합니다. 실시간 인덱스를 기대하지 않으며, 인덱스 날짜 옆의 평범한 문장은 정직하게 읽힙니다.

다른 도구와 일치하지 않는 수치

다른 크롤러는 웹의 다른 부분을 스캔합니다. DR 수치는 하나의 도구 내에서의 위치로 해석하고, 공식에 대해서는 DR 참조를 안내하세요.

수치 아래 짧은 메모를 추가하면 사후 변명보다 지원 시간을 훨씬 더 많이 절약할 수 있습니다.

두 수치가 다르면 먼저 참조 도메인 수를 비교하세요. DR 공식은 단순하므로 대부분의 불일치는 수치 차이에서 비롯됩니다.

50,000행에서 중단되는 목록

목록이 상한선에서 중단될 경우, 해당 API가 허용하는 범위 내의 정확한 답변입니다. 더 깊은 페이지를 시도하기보다는 한계점을 명시하고 페이징 안내로 링크하세요.

그 이후의 깊은 페이지는 재시도가 아닙니다. 이는 다른 쿼리이며, 이를 하나의 쿼리로 취급하면 무한 루프가 수 시간 동안 실행됩니다.

내보내기에서도 한계점이 표시되도록 하세요. 한 달 후에 스프레드시트를 열더라도 목록이 제한되었음을 확인할 수 있어야 합니다.

테이블 옆에 행 수를 표시하면 한계점이 명확한 사실로 전환됩니다. 50,000행을 본 독자는 더 좁은 질문을 요청해야 한다는 것을 알 수 있습니다.