バックリンク確認で何も返されない場合：エラー表

多くのケースに適用されるルール

ネットワーク障害はリトライしてください。401または402にはリトライしないでください。前者は数秒で解決しますが、後者は人間の介入が必要であり、頻繁にリトライするとログが埋まるだけです。

すべてのJSONレスポンスにはokフィールドが含まれており、認証済みリクエストには呼び出しコストと残高を示す_creditsフィールドも追加されます。HTTPステータスが正常に見えても、ボディのokを確認してください。

以下のリトライタイミングはエンジニアリング上のアドバイスであり、文書化された制限ではありません。当APIのドキュメントにはレート制限が公開されていないため、独自の上限を設け、控えめに保ってください。

401と402をリトライしない理由

401はキーの問題、402は残高の問題です。これらは1秒間の間隔でリトライしても解消されず、ログにノイズを追加するだけです。

待機しても402は解消されません。残高はアカウントページからチャージされるまでそのままであり、有効な対応は明確なメッセージと予算担当者へのアラートです。

401の場合はヘッダーやキーパラメータを確認し、キーが置き換えられていないか確認してください。間違ったキーで数回リトライしても何も証明されません。

無効なキーと空の残高はダッシュボードで異なる表示になります。別々のアラートに設定してください。チャージ担当者がキーのタイプミスで目覚めたり、キーローテーション担当者が残高不足で呼び出されたりしないようにします。

ネットワーク障害とバックオフ

タイムアウトや接続リセットは自己解決する可能性があるため、それらだけが再試行する価値があります。1、2、4、8秒待機し、少しジッターを追加し、4回目の試行で停止してください。

これらのタイミングはアドバイスであり、文書化された制限ではありません。独自の上限を設け、すべてのリトライをログに記録し、リトライ率が上昇した場合はアラートを出してください。リトライ率の上昇は通常、アップストリーム問題の最初の兆候です。

タイムアウトは明示的に、名前付き定数として保持してください。ライブラリのアップグレードで変化する暗黙的なデフォルトは、単一のマシンで夜間ジョブが失敗する一般的な原因です。

失敗率だけでなくアップストリームの応答時間も監視してください。失敗しないが低速な応答でもワーカーを占有する可能性があり、リトライループはその遅延を悪化させます。

呼び出し前にドメインを正規化する

失敗した呼び出しの多くはネットワークではなく入力ボックスで始まります。ユーザーはコピーしたものを何でも貼り付け、あなたのコードは API がそれを見る前にそれを単なるドメインに変換する必要があります。

スキームとパスを削除する

スキーム、パス、クエリ文字列を削除します。貼り付けられた記事のアドレスはホストになり、ホストのみがアップストリームに送信されます。

ホストも小文字にします。クリーニングを1つの関数に保持し、フォーム、バッチジョブ、テストのすべてで同じルールが実行されるようにします。

実際の貼り付け入力5〜6個でクリーニングをテストします。末尾のスラッシュとクエリ文字列を含むものが含まれます。これらのケースは、クリーンな例では決して示されないバグを浮き彫りにします。

www. の処理方法を1回だけ決める

www. のルールを1つ選び、1つの関数で適用します。そうすれば、同じサイトが2つの異なるスペルで検索されることはありません。

関数の横にルールを書き留めます。次に迷った www に遭遇する開発者は、2番目の意見ではなく、その決定を見つけることができます。

どのルールを選んでも、それを1つのファイルに保持し、そのためのテストを1つ書きます。テストは決定の記録であり、短いです。

ドメインになりえないものを拒否する

スペースや空のラベルを含む入力を拒否し、フォームに短いメッセージを表示します。拒否された文字列はコストがかかりませんが、悪い入力は失敗した呼び出しと混乱したユーザーを引き起こします。

末尾のドットは例外です。ホストの末尾の1つを削除し、それ以外は無効として扱います。

拒否をトーストではなく、フィールドの横に表示します。ユーザーが何が悪かったかを見れば、1回の試行で修正できます。

空の結果とインデックスの古さ

誰かがフォームに「check my backlink」と入力して何も得られない場合、空の答えが必ずしもエラーであるとは限りません。それはしばしば、ドメインが新しい、小さすぎる、または単にインデックスに含まれていないことを意味し、画面にはそれを示すべきです。

新しいサイト

先週立ち上げられたサイトは、インデックスに参照元ドメインがない場合があります。「まだインデックス化されていない」とインデックス日付と共に表示し、クロスチェックとして無料の overview 呼び出しを提供します。

その空の回答を長時間キャッシュしないでください。数時間程度で十分です。次の再ビルドでサイトがインデックスされる可能性があります。

インデックスが最後に再構築された日時を、分かりやすい言葉で訪問者に伝えてください。空の回答の横に日付を表示する方が、長いメッセージよりもギャップを明確に説明できます。

独自のUIに1行の注記を添えるだけで十分です。ライブインデックスを期待する人はおらず、インデックス日付の横に簡潔な文章を置くことは誠実さとして受け取られます。

他のツールと一致しない数値

異なるクローラーはウェブの異なる断片を把握します。DRの数値は1つのツールの内での位置として捉え、計算式についてはDRの用語集を参照してください。

数値の下の短い注記は、事後の謝罪よりもサポート時間を大幅に節約します。

2つの数値に差がある場合は、まず参照ドメインの数を比較してください。DRの計算式は単純なので、ほとんどの不一致は数値の違いに起因します。

50,000で制限される行

リストが上限に達した場合、その回答はAPIが許可する範囲内で正しいものです。より深いページを試すのではなく、カットオフをラベル付けし、ページネーションと50kの制限に関する注記にリンクしてください。

その先にあるより深いページは再試行ではありません。それらは異なるクエリであり、それを1つとして扱うことが、何時間もループが実行される原因となります。

エクスポート時にもカットオフを可視化してください。1ヶ月後にスプレッドシートを開いた際にも、リストが制限されていたことが分かるようにします。

テーブルの横に行数を表示することで、カットオフを可視な事実に変えます。50,000行という数字を見た読者は、より限定されたクエリを要求すべきだと理解します。