5 月 5 日、深夜 0 時。X バイラル投稿のリサーチで、Python スクリプトから X Harness Worker に POST リクエストを送ったら HTTP 403 Cloudflare Error 1010 "browser_signature_banned" が返ってきました。「リトライしないでください」と書かれた Cloudflare の素っ気ないエラーページです。同じスクリプトの別エンドポイント呼び出しは通っているのに、特定の Worker だけ拒否される。原因が分かるまで 30 分かかりました。

本記事では、X API の月$200 を $0 にするために組んだ twikit + サブ垢のスクレイピング環境で、実装中に踏んだ 4 つの破壊的変更とそれぞれの突破方法 を、スタックトレースと修正コード込みで共有します。

完成したスタック — 数字で並べる

なぜ X API ではなく twikit なのか

X API の料金体系は 2023 年に大きく変わりました。

研究目的で「フォロワー 1,000 以下なのに 5,000 いいね以上ついた投稿」を集めたいだけなら、Free は少なすぎ、Basic は重すぎる。間がありません。

そこで twikit + サブ垢 Cookie 認証 という構成にしました。X 側の内部 API を直接叩くため、追加コスト 0 円・取得上限実質なし (常識的なレートで使う限り)。ただし、X 側の仕様変更で頻繁に壊れます。本記事はその「壊れ方」と「直し方」のログです。

4 つの破壊的変更との戦い

エラー 1: Couldn't get KEY_BYTE indices

twikit の本家 d60/twikit を pip install twikit でインストールし、最初のリクエストを叩いたら出たエラーです。

``
File "...twikit/x_client_transaction/transaction.py", line 54, in get_indices
raise Exception("Couldn't get KEY_BYTE indices")
Exception: Couldn't get KEY_BYTE indices
`

Situation: ジェーン・スーのアカウント情報を client.get_user_by_screen_name("janesu112") で取得しようとした時。

Trip: スタックトレースを追うと transaction.py の get_indices() でコケている。X が認証用に使う X-Client-Transaction-Id を生成するために、X.com のホームページから JavaScript の ondemand.s バンドルを取得して、その中から「KEY_BYTE indices」と呼ばれる正規表現マッチを抽出するロジックです。

Aha: X 側が JavaScript チャンクの埋め込み形式を変更していました。旧形式は 'ondemand.s': 'HASH' という単純なキーバリューでしたが、新形式は数値の chunk ID を経由する 2 段階マッピングに変わっていました。

`
旧: 'ondemand.s': '5888cd7'
新: {20113: 'ondemand.s', ...}, {20113: '5888cd7', ...}
`

突破: phin/twikit のフォークが PR #7 でこのマッピングに対応していたので、本家の transaction.py を phin 版で置き換えました。

`python


phin/twikit が追加した resolver

# Method 2 (current): two-step chunk ID -> hash resolution
chunk_id_match = ON_DEMAND_CHUNK_ID_REGEX.search(response_str)
if chunk_id_match:
chunk_id = chunk_id_match.group(1)
hash_pattern = re.compile(rf"""[{{,]{chunk_id}:\s*['|\"]+([a-f0-9]+)['|\"]+""")
hash_match = hash_pattern.search(response_str)
if hash_match:
return f"https://abs.twimg.com/.../ondemand.s.{hash_match.group(1)}a.js"
return None
`

エラー 2: KeyError: 'urls'

`python
File "...twikit/user.py", line 102, in __init__
self.description_urls: list = legacy['entities']['description']['urls']
KeyError: 'urls'
`

Aha: legacy['xxx'] という直接アクセスは、フィールドが消えた瞬間に KeyError で死にます。防御的アクセスに書き換える のが安全です。

突破: user.py を全面的に .get() 形式に書き換え。

`python


Before (壊れる)

💡 KEY TAKEAWAYS
外部 API レスポンスを受け取るコードは、最初から dict.get(key, default) で書くべきです。dict[key] はテストが通っているうちは平気ですが、本番で API が仕様変更した瞬間に全件失敗します。

エラー 3: Cloudflare 1010 — 「お前の User-Agent は禁止」

スクレイピングが動き出して、12 キャンペーン分の Engagement Gate を一括登録する Python スクリプト (setup_campaigns.py) を書きました。X Harness の Cloudflare Worker に POST するだけのシンプルなコードです。

`python
req = request.Request(
url,
data=json.dumps(body).encode("utf-8"),
headers={
"Content-Type": "application/json",
"Authorization": f"Bearer {api_key}",
"Accept": "application/json",
},
method="POST",
)
`

`
{
"type": "https://developers.cloudflare.com/.../error-1010/",
"title": "Error 1010: Access denied",
"status": 403,
"detail": "The site owner has blocked access based on your browser's signature.",
"error_code": 1010,
"error_name": "browser_signature_banned"
}
`

Situation: X Harness Worker は別エンドポイント (/api/health、/api/x-accounts) では curl で疎通確認できていました。Python urllib からだけ弾かれる。

Aha: Cloudflare の Bot Management が Python urllib のデフォルト User-Agent (Python-urllib/3.13) を Bot 認定して 1010 でブロックしていました。「browser's signature」というエラーメッセージのとおり、UA で判別している。

`python
req = request.Request(
url,
data=json.dumps(body).encode("utf-8"),
headers={
"Content-Type": "application/json",
"Authorization": f"Bearer {api_key}",
"Accept": "application/json",
"User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36", # ← これ追加
},
method="POST",
)
`

教訓: 自社の Cloudflare Worker でも、自分の Python から弾かれることがある。Cloudflare の Bot Management は POST リクエストに対して特に厳しい。requests ライブラリ (デフォルト UA は python-requests/2.x) でも同じ症状です。

エラー 4: scenario_id が文字列リテラルのまま

最後は API スキーマの取り違えでした。Engagement Gate を登録する API ペイロードで、lineHarnessScenarioId フィールドに私が 設計書のドキュメント名を文字列リテラルのまま 入れていたのです。

`python


間違い

Situation: 12 キャンペーン分の setup_campaigns.py の CAMPAIGNS 定義を書いた時。

Aha: LINE Harness 側でシナリオを実際に POST して取得した UUID は fbbcf8ea-4eb8-4203-bf37-5279de31e7c6 でした。X Harness の Gate には UUID を入れる べきところを、設計書の人間可読名のまま入れていた。

突破: 実装フローを見直したら、Form 側の onSubmitScenarioId で UUID を指定すれば実起動するので、Gate 側はそのままでも問題ない構造でした。Form を PUT で更新して、UUID を埋めて完了。

`bash
curl -X PUT \
-H "Authorization: Bearer $LINE_KEY" \
-H "Content-Type: application/json" \
"https://line-harness.../api/forms/$FORM_ID" \
-d "{
\"onSubmitWebhookUrl\": \"https://x-harness.../api/engagement-gates/$GATE_ID/verify?username={x_username}\",
\"onSubmitScenarioId\": \"fbbcf8ea-4eb8-4203-bf37-5279de31e7c6\"
}"
`

突破できなかったもの — tweet.replies のスキーマエラー

`
ERROR: 'itemContent'
`

twikit の get_tweet_by_id() レスポンスから tweet.replies を辿ると、X 側のレスポンス構造で itemContent フィールドが見つからずに失敗します。Top50 投稿のリプライを 50 件ずつ取りたかったのですが、全件失敗しました。

修正は試みましたが、X 側のレスポンス構造が複雑で時間切れ。代替策として、取得済みの 492 投稿の本文から頻出語抽出 に切り替えました。結果として、リプ欄に近い「ペルソナの一次言語」が取得できたので、実用上は問題なく着地しています。

教訓: 全部直そうとしない。代替手段がある場合は、未解決のままでもスケジュールを優先する判断が必要です。

完成した運用環境 — MCP/agent-reach/

twikit を pip install --upgrade した瞬間に手動パッチが消えます。次は postinstall フック相当のスクリプトで、legacy['xxx'] を一括で .get(xxx, default) に置換するスクリプトを書く予定。

search_tweet("conversation_id:NNN", "Latest")` 経由でリプを取れる可能性があります。次の収集サイクルで実装する。

3. 監視ダッシュボード

twikit が壊れた瞬間に気づけるよう、毎朝のヘルスチェック (1 ツイート取得して成功率を Slack 通知) を組む。X 側のスキーマ変更は予測不能なので、検出だけは早くしたい。

次のアクション

EXBANK では、こうした 「課金前提を疑う」エンジニアリング支援 も行っています。「ウチも API 課金を見直したい」「外部ツール依存を減らしたい」と感じた方は、まず 細マッチョ企業診断 で 3 分セルフチェックしてみてください。AI と組める「業務体力」(自前で組める範囲を広げる体質) が 5 軸で可視化されます。

具体的なスクレイピング環境構築や、X / LINE Harness のクライアント案件支援は、お問い合わせフォームでご連絡ください。本記事の構成をベースに 1〜2 週間で立ち上げ可能です。