レート制限

レート制限は、リクエストの集中から 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 個）、リクエストをそれらに分散させます。認証を参照してください。

そのほかの上限

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

バッチサイズとページサイズ