J-Quants のレートリミットと HTTP 429｜「何本まで」は当てになりません

429 の実物

軽いリクエスト（日足1本）を、自制なしで連続して投げました。

HTTP 429
{"message": "Rate limit exceeded. Please try again later."}

本文はこれだけです。いつ再開してよいかの手がかりはありません。ヘッダも見ましたが、Retry-After・X-RateLimit-* の類は1つも返ってきませんでした。返ってくるのは Date だけです。

★ 止まるのは「そのエンドポイント」ではなく「契約」

/equities/bars/daily を連打して429にした直後に、まったく別の /equities/master を1本だけ投げました。

契約単位で、全部まとめて止まります。「日足で枠を使い切ったから、財務情報を取りにいこう」は通りません。複数のエンドポイントを並行して叩く造りにしていると、どれか1つの暴走で全部が巻き添えになります。

★ 「何本まで」は当てにならない

75秒あけてから、同じ連打を3回くり返しました。

倍近く違います。「60本投げたら止める」という実装は、2回目のような回で早々に429を踏みます。

では、どう書けば安全なのか。本数ではなく間隔で制御します。

復活までどれくらいか

止まってからの復活を、条件を変えて何度も測りました。

12秒から68秒までばらつきます。中央あたりは25〜30秒です。60秒待てば、実測した範囲ではすべて復活していました。

429の最中に叩き続けると、解除は遅れるのか

気になったので確かめました。429になったリクエストも枠に数えられるなら、リトライするほど待たされるはずです。

待ち方を2通りにして、交互に3回ずつ測りました。

差はありませんでした。429の最中に叩いても、解除が遅れることはないようです。

★ bulk のダウンロードは枠を食わない

これは実務でいちばん効く発見でした。J-Quants の bulk（CSVのまとめ配布）は、API から署名付きURLをもらい、そのURLから直接ファイルを落とします。URLの発行先は API ですが、ファイルの置き場所は別です。

先にURLを取っておいてから、わざと429にして試しました。

逆向きも確かめました。同じファイルを6回続けて落としたあとに API を1本投げたところ、HTTP 200 でした。

実装

直近60秒の本数を数えて、上限に近づいたら待つだけです。

import time
from collections import deque

class Limiter:
    """直近60秒の本数を数えて、上限に近づいたら待つ。"""

    def __init__(self, per_min: int = 50):
        self.per_min = per_min
        self.log = deque()

    def wait(self) -> None:
        now = time.time()
        while self.log and now - self.log[0] > 60.0:
            self.log.popleft()
        if len(self.log) >= self.per_min:
            time.sleep(60.0 - (now - self.log[0]) + 0.05)
        self.log.append(time.time())

それでも踏むことはあるので、429を拾って待ち直す側も要ります。

# 429 が来たら、待ってから1回だけやり直す
for attempt in range(3):
    limiter.wait()
    status, body = request(path, **params)
    if status != 429:
        break
    time.sleep(60)        # Retry-After は返ってこないので自分で決める
else:
    raise RuntimeError("3回試しても429でした")

上限は60本ですが、自制は50本にしています。実測で30本しか通らない回があった以上、上限ぴったりに合わせる意味がないからです。

分からなかったこと

正直に書きます。枠の数え方そのものは、最後まで決着しませんでした。

分単位の固定窓（毎分00秒でリセット）なら、復活の瞬間は毎回00秒の近くに揃うはずです。止め始める位置を分の5秒・25秒・45秒と変えて測りましたが、復活したのは19秒・15秒・3秒の位置で、揃いませんでした。

• 固定窓ではなさそう（復活の秒が揃わない）
• 単純なスライド窓でもない（通る本数が30〜60でばらつく）
• 復活までの時間も一定ではない（12〜68秒）

公式に仕様の記載を見つけられなかったので、ここは「分からない」と書いておきます。実務上は1秒に1本なら止まらないことが分かれば足ります。

まとめ

1. 本数を数えるのはやめる。30本で止まる回があります
2. 1秒に1本。これで135本連続、一度も止まりませんでした
3. 429を踏んだら60秒待つ。Retry-After は来ません
4. 全エンドポイントが同時に止まる。並行で叩く造りは巻き添えを食います
5. bulk のダウンロードは枠を食わない。消費するのは署名付きURLの発行1回だけ

レートリミットは、速く落とすための工夫より止まらない造りにしておくことのほうが効きます。1秒に1本でも、2年ぶんのティックは38回の呼び出しで揃います。