レート制限
Nodaro の API トークンは、デフォルトで 1 分あたり 30 件、最大 120 件の実行リクエストを受け付けます。ルートごとの上限、2 種類の 429 コード、バッチサイズ、バックオフの方法も説明します。
レート制限は、リクエストの集中から Nodaro API を守る仕組みです。個人用 API トークンには、それぞれ、ワークフローの実行に使える 1 分あたりの枠があります。一部のルートには、独自の上限もあります。上限を超えたリクエストには、429 Too Many Requests が返されます。ジョブや実行のポーリングは、トークンの枠に数えられません。そのため、数秒ごとにポーリングしても、枠を使い切ることはありません。
トークンごとの上限
どの個人用 API トークンにも、1 分あたりのリクエストの枠があります。
- デフォルトは 1 分あたり 30 リクエストです。上限は、トークンを作成するときにレート制限(リクエスト/分)で、1〜120 の範囲で設定します。後から変更するには、
PATCH /v1/api-tokens/:idでrateLimitを指定します。 - 対象になるのは 2 つのルートだけです:
POST /v1/api/runとGET /v1/api/workflowsです。 - 読み取りは数えられません。
GET /v1/api/status/:execId、GET /v1/api/result/:execId、GET /v1/api/schemaは、枠を消費しません。 - 枠は 1 分ごとにリセットされます。
枠を超えたリクエストには、次のレスポンスが返されます。
{ "error": { "code": "rate_limited", "message": "Too many requests. Max 30 per minute." } }もっと速く処理したい場合は、トークンの上限を 120 に引き上げます。それ以上が必要な場合は、トークンを追加で作成し(1 つのアカウントにつき最大 10 個)、リクエストをそれらに分散させます。認証を参照してください。
そのほかの上限
| ルート | 上限 | 上限を超えたときのレスポンス |
|---|---|---|
POST /v1/webhooks/:token(Webhook トリガー) | トリガーごとに、1 分あたり 10 リクエスト | 429 |
| 公開したアプリの実行 | ユーザーごとに、アプリの 1 日あたりの実行回数の上限 | 429 rate_limit_exceeded |
POST /v1/download-video | アカウントごとに、同時に実行できる動画のインポートは 4 件まで | 429 too_many_downloads |
POST /v1/video-overlay | ユーザーごとに、1 分あたり 30 リクエスト | 429 rate_limit_exceeded |
POST /v1/freecut-export | 1 分あたり 10 リクエスト | 429 rate_limit_exceeded |
POST /v1/characters/:id/train | トークンごとに、1 分あたり 3 リクエスト | 429 rate_limit_exceeded |
POST /v1/oauth/register | IP アドレスごとに、1 分あたり 10 リクエスト | 429 rate_limit_exceeded |
POST /v1/orgs | ユーザーごとに、1 時間あたり数件の新しい組織 | 429 rate_limit_exceeded |
POST /v1/workspaces/join | アカウントごとに 1 分あたり 10 回、IP アドレスごとに 1 分あたり 30 回の試行 | 429 rate_limit_exceeded |
POST /v1/workflows/:id/collaborators | アカウントごとに、1 分あたり 20 件の追加 | 429 rate_limit_exceeded |
| 使用状況の CSV エクスポート | ユーザーごとに、1 分あたり 10 回 | 429 rate_limit_exceeded |
POST /v1/orgs/:id/invitations | 組織ごとに、1 日あたり 500 件の招待 | 429 bulk_invite_cap_exceeded |
GET /v1/invitations/by-token/:token、GET /v1/shots/:id、SSO ログインの交換エンドポイント | IP アドレスごとの上限 | 429 rate_limit_exceeded |
2 種類の 429 コード
rate_limitedは、/v1/api/のルートの、トークンごとの枠からだけ返されます。rate_limit_exceededは、それ以外のすべての上限から返されます。トークンが不要な一部のルートでの IP アドレスごとの上限、特定のルートでの呼び出し元ごとの上限、公開したアプリの 1 日あたりの実行回数です。
呼び出し元ごとの上限があるルートは、Retry-After ヘッダーを送ります。クレジットを消費するルートでは、サーバーが上限を確認できない場合に、503 rate_limit_unavailable が返されます。
再試行のロジックは、429 というステータスで判定してください。コードは、トークンごとの枠とそれ以外の上限を区別するためだけに使います。
上限への対処法
- ポーリングは 2〜5 秒ごとにする。実行の状態は秒単位で変わるため、それより頻繁にポーリングしても得るものはありません。
- 多くのジョブを 1 回の呼び出しでポーリングする。
GET /v1/jobs/statusとPOST /v1/jobs/batch-statusは、それぞれ最大 100 件のジョブを返します。ジョブを参照してください。 429には指数バックオフで対応する:再試行の前に、5 秒、10 秒、20 秒と待ち時間を延ばします。Retry-Afterがある場合は、少なくともその時間だけ待ちます。- それ以外の
4xxエラーは、確定した失敗として扱う。再試行せずに、リクエストを修正してください。エラーを参照してください。
import { RateLimitedError } from '@nodaro/sdk'
async function withBackoff<T>(call: () => Promise<T>): Promise<T> {
for (const seconds of [5, 10, 20]) {
try {
return await call()
} catch (err) {
if (!(err instanceof RateLimitedError)) throw err
await new Promise((r) => setTimeout(r, seconds * 1_000))
}
}
return call()
}
const { executionId } = await withBackoff(() => client.workflows.run(workflowId))バッチサイズとページサイズ
| エンドポイント | 上限 |
|---|---|
GET /v1/jobs/status?ids=… | 最大 100 個の ID |
POST /v1/jobs/batch-status | 最大 100 個の ID |
GET /v1/jobs | limit は最大 100 |
GET /v1/characters | limit は最大 500、デフォルトは 100 |
GET /v1/objects, /v1/creatures, /v1/locations, /v1/faces | limit は最大 500 |
GET /v1/credits/transactions | limit は 1〜50、デフォルトは 20 |
POST /v1/credits/model-costs | 最大 50 個のモデル ID |
GET /v1/community/browse | limit は最大 50、デフォルトは 20 |
GET /v1/orgs/:id/members | limit は最大 200、デフォルトは 50 |
POST /v1/orgs/:id/invitations | 1 回の呼び出しで最大 200 件のアドレス |
| API トークン | 1 つのアカウントにつき 10 個 |
| OAuth の開発者アプリ | 1 人のユーザーにつき、手動で登録できるのは 5 個 |
よくある質問
Nodaro の API トークンのレート制限はどれくらいですか?
デフォルトでは 1 分あたり 30 リクエストで、トークンごとに 120 リクエストまで引き上げられます。制限の対象は、ワークフローの実行とワークフローの一覧表示、つまり POST /v1/api/run と GET /v1/api/workflows だけです。
ポーリングは、レート制限の対象になりますか?
いいえ。実行のステータスや結果、ワークフローのスキーマを読み取っても、トークンの枠は消費されません。ジョブのステータスの読み取りも同様です。ポーリングは 2〜5 秒ごとに行ってください。
429 エラーが返されたら、どうすればよいですか?
時間をおいて、指数バックオフで再試行します。たとえば、5 秒後、10 秒後、20 秒後に再試行します。レスポンスに Retry-After ヘッダーがある場合は、少なくともその時間だけ待ってください。再試行のロジックは、エラーコードではなく 429 というステータスで判定してください。
より高いレート制限を使うには、どうすればよいですか?
トークンのレート制限を、1 分あたり 120 リクエストまで引き上げます。それ以上が必要な場合は、トークンを追加で作成し(1 つのアカウントにつき最大 10 個)、リクエストをそれらに分散させます。
Webhook トリガーにも、レート制限はありますか?
はい。API トークンとは別の制限があります。各 Webhook トリガーは、それぞれの URL で 1 分あたり 10 リクエストを受け付けます。
関連ページ
認証
エラー
ジョブ
Webhook
ワークフロー
最終更新