# レート制限

> Nodaro の API トークンは、デフォルトで 1 分あたり 30 件、最大 120 件の実行リクエストを受け付けます。ルートごとの上限、2 種類の 429 コード、バッチサイズ、バックオフの方法も説明します。

Source: https://nodaro.ai/ja/docs/developers/api/rate-limits

**レート制限**は、リクエストの集中から 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 分ごとにリセットされます**。

枠を超えたリクエストには、次のレスポンスが返されます。

```json
{ "error": { "code": "rate_limited", "message": "Too many requests. Max 30 per minute." } }
```

もっと速く処理したい場合は、トークンの上限を 120 に引き上げます。それ以上が必要な場合は、トークンを追加で作成し（1 つのアカウントにつき最大 10 個）、リクエストをそれらに分散させます。[認証](https://nodaro.ai/docs/developers/api/authentication)を参照してください。

## そのほかの上限
| ルート | 上限 | 上限を超えたときのレスポンス |
| --- | --- | --- |
| `POST /v1/webhooks/:token`（[**Webhook トリガー**（Webhook Trigger）](https://nodaro.ai/docs/nodes/automate/webhook-trigger)） | トリガーごとに、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 件のジョブを返します。[ジョブ](https://nodaro.ai/docs/developers/api/jobs#poll-many-jobs-at-once)を参照してください。
- **`429` には指数バックオフで対応する**：再試行の前に、5 秒、10 秒、20 秒と待ち時間を延ばします。`Retry-After` がある場合は、少なくともその時間だけ待ちます。
- **それ以外の `4xx` エラーは、確定した失敗として扱う**。再試行せずに、リクエストを修正してください。[エラー](https://nodaro.ai/docs/developers/api/errors)を参照してください。

```ts

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 個 |

## Frequently asked questions

### 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 リクエストを受け付けます。