切断への対処

​

切断とは何ですか？

streaming API への接続を確立するとは、非常に長期間持続する HTTPS リクエストを送信し、レスポンスを逐次的に処理することを指します。Filtered stream endpoint に接続する場合は、HTTPS リクエストを発行し、実用的な限り長く得られる stream を消費し続けてください。サーバー側のエラー、クライアント側の過度な遅延、ネットワークの問題、定期的なサーバーメンテナンス、重複ログインなどがない限り、当社のサーバーは接続を無期限に維持します。streaming endpoint への接続では切断が発生する可能性が高く、想定しておくべきものです。そのため、再接続のロジックを実装しておいてください。  

​

stream 接続が切断されうる理由

stream はさまざまな理由で切断されることがあります。原因を特定するため、stream から返されるエラーメッセージを確認してください。切断される主な理由は次のとおりです。

• 認証エラー（誤ったトークンの使用や、誤った認証方式の利用など）。
• X 側で streaming サーバーが再起動された場合。これは通常、コードのデプロイに伴うもので、発生を想定し、その前提で設計しておく必要があります。
• クライアントが stream で配信される Posts の量に追従できていない、または data の読み取りが遅すぎる場合。すべての streaming 接続にはクライアント送信用のメッセージキューがあり、このキューが時間の経過とともに過度に増大すると、接続は終了されます。
• アカウントが日次/月次の Posts のクォータを超過した場合。
• アクティブな冗長接続が多すぎる場合。
• クライアントが突然 data の読み取りを停止した場合。stream から読み取られる Posts のレートが急激に低下すると、接続は終了されます。
• サーバーとクライアント間のネットワーク問題の可能性。
• 一時的なサーバー側の問題、計画メンテナンスやアップデート。（ステータスページを確認してください）  

​

一般的な切断エラーには、次のようなものがあります：

	"errors": [{
		"title": "operational-disconnect",
		"disconnect_type": "UpstreamOperationalDisconnect",
		"detail": "このstreamは運用上の理由により上流側で切断されました。",
		"type": "https://api.x.com/2/problems/operational-disconnect"
	}]
}

{
	"title": "ConnectionException",
	"detail": "このstreamは現在、許可されている最大接続数の制限に達しています。",
	"connection_issue": "TooManyConnections",
	"type": "https://api.x.com/2/problems/streaming-connection"
}

​

切断を想定し再接続する

Posts をストリーミングする際の目標は、切断が起こり得ることを認識しつつ、可能な限り長く接続を維持することです。endpoint は 20 秒ごとにキープアライブのハートビートを送信します（改行文字として現れます）。このシグナルを用いて切断の兆候を検出してください。

1. 新しいコンテンツとハートビートの受信が止まったことをコードで検出してください。
2. その場合は再接続ロジックを起動してください。クライアントや言語によっては読み取りタイムアウトを指定でき、20 秒に設定できます。
3. サービスはこれらの切断を検知し、可能な限り速やかに再接続する必要があります。

確立済みの接続が途切れたら、直ちに再接続を試みてください。再接続に失敗した場合は、発生したエラーの種類に応じて再試行の間隔を延ばしてください。

• TCP/IP レベルのネットワークエラーの場合は線形バックオフを行ってください。これらの問題は一般的に一時的で、すぐに解消される傾向があります。試行のたびに再接続の遅延を 250ms ずつ増やし、最大 16 秒までにします。
• 再接続が適切な HTTP エラーの場合は指数バックオフを行ってください。最初は 5 秒待機し、試行のたびに倍にして最大 320 秒までにします。
• HTTP 429（レートリミット超過）の場合は指数バックオフを行ってください。最初は 1 分待機し、試行のたびに倍にします。HTTP 429 を受け取るたびに、アカウントのレートリミットが解除されるまでに待機すべき時間が増える点に注意してください。  

​

失われたデータの復旧

切断が発生した場合に、取り逃した可能性のあるデータを漏れなく受信するための複数の戦略があります。見逃したデータを回復するための主要な手順については、統合ガイド「データ復旧」にまとめています。   

​

レートリミットと利用状況

接続の上限を確認するには、レスポンスに含まれる3つのヘッダーを参照します。これは、rule endpoint をどの程度利用できるか、また streaming endpoint に対して何回の再接続試行が許可されているかを把握するのに有用です。

• x-rate-limit-limit は、15分のウィンドウ内にクライアントが実行可能なリクエストの上限数を示します。

• x-rate-limit-remaining は、15分のウィンドウ内で残っているリクエスト数を示します。

• x-rate-limit-reset は、15分のウィンドウが再開し、x-rate-limit-remaining が 0 にリセットされる時刻を示す UNIX タイムスタンプです。

filter stream endpoint は現在、利用状況データを報告しません。配信された Posts の件数を把握するには、必要に応じて消費量を計測し一時停止できるよう、コード側でメータリングのロジックを実装してください。

stream のクライアント側をホストするコードは、受信した Posts を先入れ先出し（FIFO）キューまたは同様のメモリ構造に挿入するだけです。別のプロセス／スレッドがそのキューから Posts を取り出して解析し、保存用に準備します。この設計により、受信する Post のボリュームが大きく変動した場合でも、効率的にスケールできるサービスを実装できます。概念的には、HTTP 経由で無限長のファイルをダウンロードしているイメージです。

​

再接続に関するベストプラクティス

バックオフ戦略をテストする

バックオフの実装を検証する有効な方法は、不正な認可情報を使って再接続の挙動を観察することです。適切に実装されていれば、429 応答は発生しません。

複数回の再接続に対するアラートを出す

クライアントが再接続間隔の上限しきい値に達した場合は、接続に影響する問題を切り分けられるよう、通知を送信する必要があります。

DNS 変更への対応

クライアントプロセスが DNS の Time To Live (TTL) を順守することを確認してください。スタックによっては、プロセスの存続期間中に解決済みアドレスをキャッシュし、規定 TTL 内の DNS 変更を反映しないものがあります。このような過度なキャッシュは、X が IP アドレス間で負荷分散を行う際に、クライアント側でサービス障害を引き起こす原因になります。

User Agent

user-agent HTTP ヘッダーにクライアントのバージョンを含めてください。これは X 側での問題診断に不可欠です。環境の制約で user-agent フィールドを設定できない場合は、x-user-agent ヘッダーを設定してください。