基本概念

レート制限

各キーは1分あたり120リクエストまで送信できます。残りの回数は、すべてのレスポンスで確認できます。

制限

制限	適用対象
1分あたり120リクエスト	APIキーごとに、すべてのエンドポイントが対象です。1分の区切りは固定ウィンドウで、毎分0秒に始まります。
1時間あたり10回のエクスポート	アカウントごとに、エクスポートを作成が対象です。超えると429 `export_rate_limit_exceeded`が返ります。
1分あたり10件のDM	Xアカウントごとに、メッセージを送信が対象です。超えると429 `dm_rate_limited`が返ります。
1日あたり300件のDM	Xアカウントごとに、UTCの1日単位で数えます。Xがより低い上限を設けている場合はそちらが優先されます。超えると429 `dm_daily_limit`が返ります。
パスコードの試行は1時間あたり5回	アカウントごとに、X Chatのパスコードを設定が対象です。超えると429 `passcode_rate_limited`が返ります。
Julien AIへのメッセージは1分あたり6件	Xアカウントごとに、メッセージを送信とMCPツール`ask_julien_ai`が対象です。超えると429 `assistant_rate_limited`が返ります。
Julien AIへのメッセージは1日あたり100件	Xアカウントごとに、UTCの1日単位で数えます。超えると429 `assistant_daily_limit`が返ります。
Julien AIへのメッセージは一度に1件	チャットごとに1件、Xアカウントごとに同時に3チャットまでです。超えると409 `assistant_busy`が返ります。

レート制限のヘッダー

すべてのレスポンスに、キーの現在のウィンドウの状態が含まれます。

ヘッダー	意味
`RateLimit-Limit`	1ウィンドウで許可されるリクエスト数。`120`です。
`RateLimit-Remaining`	現在のウィンドウで残っているリクエスト数。
`RateLimit-Reset`	次のウィンドウが始まるまでの秒数。
`Retry-After`	429のときのみ。再試行までに待つ秒数。

ヘッダー

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
RateLimit-Limit: 120
RateLimit-Remaining: 0
RateLimit-Reset: 17
Retry-After: 17
Request-Id: req_3Vb8YzC1dF6hJ0sW

レスポンス429

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Too many requests. This key can make 120 requests a minute.",
    "param": null,
    "request_id": "req_3Vb8YzC1dF6hJ0sW",
    "doc_url": "https://gemlead.ai/docs/errors#rate_limit_exceeded"
  }
}

429への対処

Retry-After秒待ってから、同じリクエストを再送してください。

大きな処理は一度にまとめて送らず、時間をかけて分散させてください。
RateLimit-Remainingを確認し、0になる前にペースを落としてください。
多くのリードを一度に取得するなら、何百ページも取得するよりエクスポートを1回行うほうが効率的です。
Webhookならイベントが自動で届くため、新しいリードを確認するポーリングでリクエストを消費することはありません。

# curl waits for Retry-After, then tries again
curl --retry 5 https://gemlead.ai/api/v1/leads \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"