APIの「無効なリンク」エラー：注文作成前のURLチェック

APIの「無効なリンク」エラーとは

「無効なリンク」エラーは、APIが注文のターゲットフィールドのURLを受け付けられなかったことを意味します。必ずしもアドレスの打ち間違いとは限りません。不適切な形式、ページ種別、リダイレクト、アクセス制限、エンコード、またはプラットフォームとサービスの不一致が原因で、サービスがリンクを拒否することがあります。

通常、チェックは注文作成前に行われます。APIはURLを受け取り、ドメインとパスを判定し、チャンネル、動画、配信、投稿、プロフィールなどのオブジェクトを識別しようとします。いずれかの段階で失敗すると、注文は作成されません。エラーの一般的な文言だけでは原因は分かりません。URL、サービスのパラメータ、APIの完全なレスポンスを確認する必要があります。

エラー文言とAPIレスポンスを照合する

APIによって文言やレスポンスの構造は異なります。メッセージのみを返す場合もあれば、コード、フィールド名、リクエストIDを追加する場合もあります。HTTPステータスよりも完全なレスポンスの方が有用です。リクエストが正常に届いても、APIがビジネスチェックの段階で注文自体を拒否することがあるためです。

たとえば、典型的なレスポンスは次のようになります：{"error":"invalid_link","message":"Invalid target URL","field":"link"}。この場合はlinkフィールドの値を確認してください。{"error":"target_not_supported"}というパターンは、壊れたアドレスではなく、サポートされていないオブジェクト種別を示すことが多いです。フィールド名やコードは具体的なドキュメントによって異なります。

レスポンスのステータス、レスポンスボディ、サービスID、APIが返す場合はrequest_idを保存してください。チケットにアクセストークン、cookie、リクエスト署名、リンクの非公開パラメータを含めないでください。

URL形式とリクエストフィールドの値を確認する

ブラウザで動作するリンクが機械的なチェックを通過しないことがあります。フィールドに動画IDだけ、ドメインなしのニックネーム、メッセージのテキスト、短縮アドレスが入ってしまう場合があります。URLが文字列ではなくネストされたオブジェクトや配列として渡された場合にもエラーが発生します。

• プロトコルhttps://を含む完全な公開URLを渡してください。
• ドメインを確認してください。選択したサービスのプラットフォームに属している必要があります。
• 前後の空白、改行、絵文字、リンクの後ろのテキストを削除してください。
• フィールド名をAPIドキュメントと照合してください：link、url、targetなど。
• リクエストでURLを含むオブジェクトではなく、文字列値が渡されていることを確認してください。

アドレスの手動貼り付けは便利ですが、欠点があります。見えない文字や投稿のキャプションの断片が文字列に紛れ込みやすいのです。送信前に値をクリアしてください。ただし、必要なくパスやパラメータ自体を変更しないでください。

短縮リンクを展開し、余分なリダイレクトを除去する

短縮アドレスや「共有」ボタンからのリンクは、1つまたは複数のリダイレクトを経由することがよくあります。ブラウザは自動的に開きますが、プロモーションサービスのAPIはリダイレクトをたどれない、ブロックする、または中間の認証ページを取得することがあります。

注文には正規のアドレス、つまり目的のページが完全に読み込まれた後にアドレスバーに表示されるアドレスを使用するのが最適です。キャンペーンのタグや再生時間のパラメータは必ずしも問題になりませんが、パラメータによってページの表示が変わったり、オブジェクトの識別に影響したりすることがあります。

正規URLには欠点があります。特にモバイルアプリからリンクをコピーした場合、別途取得が必要になることがあります。ただし、そのようなアドレスは手動で確認しやすく、サービスのルールと照合しやすいです。

サービスが受け付けるオブジェクトへのリンクを選択する

サービスは1種類のターゲットのみを受け付ける場合があります。チャンネル向けの注文は配信アーカイブへのリンクを受け付けず、動画再生回数向けのサービスは作者のプロフィールを受け付けません。外見上はどちらのURLも正しいですが、APIはアドレスの構造をサービスの目的と照合し、不適切なオブジェクトを拒否します。

サービスの一覧を確認してください：プラットフォーム、カテゴリ、許容されるtarget_type、制限。APIがターゲット種別の個別パラメータを要求する場合、それはURLと一致している必要があります。コンテンツのアドレスを検索、ハッシュタグ、コレクション、トップページ、作者のアカウントページへのリンクに置き換えないでください。

• チャンネルプロモーションにはチャンネルページを渡してください。
• 再生回数には特定の動画または投稿へのリンクを使用してください。
• アクティブな配信には、サービスがライブ形式をサポートしている場合、配信のURLを渡してください。
• リアクションや投稿へのその他のアクションには、投稿への直接リンクを使用してください。

公開設定、年齢制限、ログイン要件を確認する

APIはURLの形式だけでなく、ターゲットのアクセス可否も確認します。コンテンツはチャンネル所有者のブラウザが認証されているために開けるものの、外部のチェックサーバーからはアクセスできない場合があります。この場合、サービスは無効なリンクに関する一般的なエラーを返すことがよくあります。

• プロフィール、チャンネル、投稿、配信自体が非公開になっていないか確認してください。
• 動画が削除されていない、下書きに移動されていない、別の投稿に置き換えられていないことを確認してください。
• 年齢制限を確認してください。年齢確認やアカウントログインが必要な場合があります。
• 購読者、メンバー、承認済み視聴者のみのアクセスモードが有効になっている場合は無効にしてください。
• ページにログインフォーム、コンテンツ警告、技術的なプレースホルダーが表示されていないことを確認してください。

認証なしのプライベートウィンドウでリンクを開いてください。目的のページではなくログイン要求が表示される場合は、アクセス設定を変更するか、そのようなターゲット種別を許可するサービスが用意されている場合はそれを選択してください。プライベートウィンドウでのチェックの欠点は、地域制限やネットワーク制限を常に検出できるわけではないことです。

地域別、モバイル、埋め込みアドレスに注意する

1つのオブジェクトにデスクトップ、モバイル、ローカライズ、埋め込みのURLが存在することがあります。アプリやwebviewからのアドレスには、APIが認識しない技術的なセグメントが含まれることがあります。ローカライズされたページも、チェックサーバーからは異なって表示される場合があります。

コピーしたリンクを通常のブラウザで開き、完全に読み込まれるまで待ってください。リクエストにはアドレスバーに表示される公開ウェブアドレスを使用してください。コンテンツが地域制限されている場合は、プラットフォームの設定で許可されていれば制限を解除するか、公開アクセスが必要なサービスにそのようなターゲットを送信しないでください。

認証や中間画面のない公開ウェブリンクが、APIチェックに最も信頼できる選択肢です。

リクエスト送信時のURL破損を排除する

リンクは送信前は正しくても、JSONのシリアライズ、クエリパラメータの組み立て、form-dataの送信、再エンコードの際に変化することがあります。特に&、?、#、%の記号は影響を受けやすいです。たとえば、URL内のアンパサンドは、アドレスが必要なエンコードなしで渡されると、リクエスト自体のパラメータ区切り文字になることがあります。

• 元のURLと実際のHTTPリクエスト内の値を比較してください。
• クライアント、プロキシ、開発者ツールのログでリクエストボディを確認してください。
• JSONには手動の文字列組み立てではなく、標準のシリアライズを使用してください。
• ライブラリが自動で行う場合、URLを二重にエンコードしないでください。
• パスとアドレスパラメータ内のキリル文字の処理を確認してください。

ログは不一致を素早く見つけるのに役立ちますが、欠点があります。APIキー、トークン、個人データが含まれる可能性があるのです。記録やログの送信前に機密値をマスクしてください。

プラットフォーム、サービスID、注文パラメータを照合する

一部の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の完全なレスポンスとリクエストIDを保存してください。

これらのチェック後もエラーが続く場合は、サポートにクリーンな形式のリンク、サービスID、リクエスト時刻、HTTPステータス、APIレスポンスの全文を送ってください。これにより、URLの問題と特定のサービスの制限やサービス側のチェック障害を区別できます。