API의 "잘못된 링크" 오류: 주문 생성 전 URL 검증

API의 "잘못된 링크" 오류의 의미

"잘못된 링크" 오류는 API가 주문 대상 필드의 URL을 받아들이지 못했다는 뜻입니다. 항상 주소의 오타 때문만은 아닙니다. 서비스는 부적합한 형식, 페이지 유형, 리디렉션, 접근 제한, 인코딩 또는 플랫폼과 서비스의 불일치로 인해 링크를 거부할 수 있습니다.

검증은 보통 주문 생성 전에 이루어집니다. API는 URL을 받아 도메인과 경로를 확인하고 채널, 동영상, 라이브 방송, 게시물 또는 프로필 등 객체를 인식하려고 시도합니다. 이 중 하나라도 통과하지 못하면 주문이 생성되지 않습니다. 일반적인 오류 문구만으로는 원인을 알 수 없으므로 URL, 서비스 매개변수, 전체 API 응답을 확인해야 합니다.

오류 문구와 API 응답을 대조하세요

API마다 응답의 표현과 구조가 다릅니다. 때로는 서비스가 메시지만 반환하고, 때로는 코드, 필드 이름 또는 요청 식별자를 추가합니다. 전체 응답이 HTTP 상태보다 유용합니다. 요청이 성공적으로 전달되더라도 API가 비즈니스 검증 단계에서 주문 자체를 거부할 수 있기 때문입니다.

예를 들어 일반적인 응답은 다음과 같을 수 있습니다: {"error":"invalid_link","message":"Invalid target URL","field":"link"}. 이 경우 link 필드의 값을 확인해야 합니다. {"error":"target_not_supported"} 같은 경우는 주소가 깨진 것이 아니라 지원되지 않는 객체 유형을 나타내는 경우가 많습니다. 필드 이름과 코드는 구체적인 문서에 따라 다릅니다.

응답 상태, 응답 본문, 서비스 식별자, 그리고 API가 반환하는 경우 request_id를 저장하세요. 티켓에 액세스 토큰, 쿠키, 요청 서명 및 링크의 비공개 매개변수를 추가하지 마세요.

URL 형식과 요청 필드 값을 확인하세요

브라우저에서 작동하는 링크가 기계 검증을 통과하지 못할 수 있습니다. 필드에 동영상 식별자만, 도메인 없는 닉네임, 메시지의 텍스트 또는 단축 주소가 들어가는 경우가 있습니다. URL이 문자열이 아니라 중첩 객체나 배열로 전달될 때도 오류가 발생합니다.

• https:// 프로토콜을 포함한 전체 공개 URL을 전달하세요.
• 도메인을 확인하세요: 선택한 서비스의 플랫폼에 속해야 합니다.
• 앞뒤 공백, 줄바꿈, 이모지 및 링크 뒤의 텍스트를 제거하세요.
• 필드 이름을 API 문서와 대조하세요: link, url, target 또는 기타.
• 요청에 URL이 담긴 객체가 아니라 문자열 값이 전달되는지 확인하세요.

주소를 수동으로 붙여넣는 것은 편리하지만 단점이 있습니다. 문자열에 보이지 않는 문자나 게시물 설명의 일부가 쉽게 들어갈 수 있습니다. 전송 전에 값을 정리하되, 필요하지 않다면 경로와 매개변수 자체를 변경하지 마세요.

단축 링크를 펼치고 불필요한 리디렉션을 제거하세요

축약 주소와 "공유" 버튼의 링크는 종종 하나 이상의 리디렉션을 거칩니다. 브라우저는 이를 자동으로 열지만, 프로모션 서비스의 API는 리디렉션을 따라가지 않거나 차단하거나 중간 인증 페이지를 받을 수 있습니다.

주문에는 정규 주소, 즉 원하는 페이지가 완전히 로드된 후 주소 표시줄에 보이는 주소를 사용하는 것이 좋습니다. 캠페인 태그와 시청 시간 매개변수가 항상 방해가 되는 것은 아니지만, 매개변수가 페이지의 다른 표현으로 이어지거나 객체 인식에 영향을 줄 수 있습니다.

정규 URL에는 단점이 있습니다. 특히 모바일 앱에서 링크를 복사한 후에는 별도로 얻어야 하는 경우가 있습니다. 대신 이러한 주소는 수동으로 확인하고 서비스 규칙과 대조하기가 더 쉽습니다.

서비스가 받아들이는 객체의 링크를 선택하세요

서비스는 하나의 대상 유형만 받아들일 수 있습니다. 채널용 주문은 방송 녹화 링크를 받지 않으며, 동영상 조회수 서비스는 작성자 프로필을 받지 않습니다. 겉으로 보기에는 두 URL 모두 올바르지만, API는 주소 구조를 서비스 목적과 대조하여 부적합한 객체를 거부합니다.

서비스 목록을 확인하세요: 플랫폼, 카테고리, 허용되는 target_type 및 제한 사항. API가 대상 유형에 대한 별도 매개변수를 요구하는 경우 URL과 일치해야 합니다. 콘텐츠 주소를 검색, 해시태그, 컬렉션, 메인 페이지 또는 작성자 페이지 링크로 대체하지 마세요.

• 채널 프로모션에는 채널 페이지를 전달하세요.
• 조회수에는 특정 동영상 또는 게시물 링크를 사용하세요.
• 진행 중인 방송에는 서비스가 라이브 형식을 지원하는 경우 방송 URL을 전달하세요.
• 반응 및 게시물에 대한 기타 작업에는 게시물의 직접 링크를 사용하세요.

공개 여부, 연령 제한 및 로그인 요구 사항을 확인하세요

API는 URL 형식뿐만 아니라 대상의 접근 가능 여부도 확인합니다. 콘텐츠가 채널 소유자의 브라우저에서는 인증되어 열리지만 외부 검증 서버에서는 접근할 수 없을 수 있습니다. 이 경우 서비스는 종종 잘못된 링크에 대한 일반 오류를 반환합니다.

• 프로필, 채널, 게시물 또는 방송 자체가 비공개로 설정되어 있지 않은지 확인하세요.
• 동영상이 삭제되지 않았고, 임시 저장으로 이동되지 않았으며, 다른 게시물로 대체되지 않았는지 확인하세요.
• 연령 제한을 확인하세요: 연령 확인 또는 계정 로그인이 필요할 수 있습니다.
• 구독자, 멤버 또는 승인된 시청자 전용 액세스 모드가 활성화되어 있다면 비활성화하세요.
• 페이지에 로그인 양식, 콘텐츠 경고 또는 기술적 대체 화면이 표시되지 않는지 확인하세요.

인증 없이 시크릿 창에서 링크를 여세요. 대상 페이지 대신 로그인 요청이 표시되면 액세스 설정을 변경하거나, 해당 대상 유형을 허용하는 서비스가 있다면 그러한 서비스를 선택하세요. 시크릿 창에서의 확인에는 단점이 있습니다. 지역적 및 네트워크 제한을 항상 발견하지는 못합니다.

지역별, 모바일 및 임베디드 주소를 고려하세요

하나의 객체에 데스크톱, 모바일, 현지화 및 임베디드 URL이 있을 수 있습니다. 앱이나 웹뷰에서 가져온 주소에는 API가 인식하지 못하는 기술적 세그먼트가 포함될 수 있습니다. 현지화된 페이지도 검증 서버에서 다르게 열릴 수 있습니다.

복사한 링크를 일반 브라우저에서 열고 완전히 로드될 때까지 기다리세요. 요청에는 주소 표시줄의 공개 웹 주소를 사용하세요. 콘텐츠가 지역별로 제한되어 있다면 플랫폼 설정이 허용하는 경우 제한을 제거하거나, 공개 액세스가 필요한 서비스에 그러한 대상을 보내지 마세요.

인증과 중간 화면이 없는 공개 웹 링크가 API 검증에 가장 안정적인 옵션입니다.

요청 전송 시 URL 손상을 배제하세요

링크는 전송 전에는 올바르지만 JSON 직렬화, 쿼리 매개변수 구성, form-data 전송 또는 재인코딩 중에 변경될 수 있습니다. 특히 &, ?, # 및 % 기호에 민감합니다. 예를 들어 URL의 앰퍼샌드는 주소가 필요한 인코딩 없이 전달되면 요청 자체의 매개변수 구분자가 될 수 있습니다.

• 원본 URL과 실제 HTTP 요청의 값을 비교하세요.
• 클라이언트 로그, 프록시 또는 개발자 도구에서 요청 본문을 확인하세요.
• JSON에는 수동 문자열 구성이 아닌 표준 직렬화를 사용하세요.
• 라이브러리가 자동으로 수행하는 경우 URL을 두 번 인코딩하지 마세요.
• 경로와 주소 매개변수의 키릴 문자 처리를 확인하세요.

로그는 불일치를 빠르게 찾는 데 도움이 되지만 단점이 있습니다. API 키, 토큰 및 개인 데이터가 포함될 수 있습니다. 기록 및 로그 전송 전에 민감한 값을 마스킹하세요.

플랫폼, 서비스 식별자 및 주문 매개변수를 대조하세요

일부 API는 먼저 서비스를 확인한 다음 도메인과 링크 유형을 확인합니다. 다른 플랫폼의 URL, 오래된 service_id 또는 잘못된 target_type도 동일한 "잘못된 링크" 오류로 이어질 수 있습니다. 이 경우 주문 매개변수가 수정될 때까지 주소 자체를 변경하는 것은 무의미합니다.

API 메서드가 제공되는 경우 이를 통해 서비스 카탈로그를 업데이트하세요. 오래된 목록이 있는 캐시에는 비활성화된 서비스나 이전 요구 사항이 저장될 수 있습니다. 카탈로그를 자주 업데이트하면 단점이 있습니다. 요청 수가 증가하고 속도 제한에 부딪힐 수 있습니다. 제한된 보관 기간의 캐시를 사용하고 검증 오류 후에 업데이트하세요.

재전송 전에 링크를 순서대로 확인하세요

1. 텍스트, 공백 및 숨겨진 문자 없이 전체 URL을 복사하세요.
2. 계정에 로그인하지 않고 시크릿 창에서 여세요.
3. 페이지가 비공개, 삭제 또는 로그인 요구 상태가 아닌지 확인하세요.
4. 연령, 구독 또는 지역 제한이 없는지 확인하세요.
5. 단축 링크를 최종 공개 주소로 펼치세요.
6. URL의 객체를 서비스와 대조하세요: 채널, 동영상, 방송 또는 게시물.
7. 플랫폼, service_id 및 target_type을 최신 서비스 카탈로그와 대조하세요.
8. 실제 HTTP 요청 본문과 URL 인코딩을 확인하세요.
9. 토큰과 비공개 데이터 없이 전체 API 응답과 요청 식별자를 저장하세요.

이러한 확인 후에도 오류가 지속되면 지원팀에 정리된 링크, 서비스 식별자, 요청 시간, HTTP 상태 및 전체 API 응답 텍스트를 전달하세요. 이를 통해 URL 문제와 특정 서비스의 제한 또는 서비스 측 검증 오류를 구분할 수 있습니다.