Unif API Docsレート制限
API キー単位のリクエスト制限、すべてのレスポンスが返すヘッダー、そしてエージェントがペースを調整する方法。
UnifAPI のリクエスト制限は 1 つだけです。API キーごとに 60 秒あたり 60 リクエスト。制限の単位はキーであり、ワークスペースやエンドポイントではありません。同じワークスペースの 2 つのキーが同じ枠を奪い合うことはなく、個別に厳しい制限を持つ操作もありません。
ヘッダー
2xx、4xx、5xx を問わず、すべてのレスポンスがそのリクエストに適用される枠を返します。現在の状況を知るために探りのリクエストを送る必要はありません。
| ヘッダー | 意味 |
|---|---|
RateLimit-Policy | IETF 構造化フィールド形式のポリシー: "api-key";q=60;w=60（q はリクエスト数、w はウィンドウ秒数） |
RateLimit | 同じ形式の現在値: "api-key";r=<残り>;t=<リセットまでの秒数> |
RateLimit-Limit | 1 ウィンドウで許可されるリクエスト数 |
RateLimit-Remaining | 現在のウィンドウで残っているリクエスト数 |
RateLimit-Reset | ウィンドウがリセットされるまでの秒数。Unix タイムスタンプではなく相対値です |
X-RateLimit-Limit / -Remaining / -Reset | 上記 3 つの別名。X- 表記しか読まないクライアント向け |
Retry-After | 待機秒数。UnifAPI 自身が返した 429 に付きます |
API キーが解決されなかったレスポンス（たとえば 401）は、既定のポリシーを満枠のまま返します。これは消費済みの使用量ではなく、認証後に適用される枠を示すものです。
ブラウザーからの呼び出しでもすべて読み取れます。クロスオリジンのレスポンスでは Access-Control-Expose-Headers に列挙されています。
HTTP/1.1 200 OK
RateLimit-Policy: "api-key";q=60;w=60
RateLimit: "api-key";r=57;t=60
RateLimit-Limit: 60
RateLimit-Remaining: 57
RateLimit-Reset: 60ウィンドウの挙動
ウィンドウはそのキーの直近のリクエストを起点とします。そのキーからの呼び出しがないまま 1 ウィンドウが経過すると、カウンターはリセットされます。バースト用の余裕はないため、貯めた残高ではなく定常レートを前提に設計してください。
429 の扱い
async function call(url: string, init: RequestInit, attempt = 0): Promise<Response> {
const res = await fetch(url, init);
if (res.status !== 429 || attempt >= 5) return res;
const wait = Number(res.headers.get("Retry-After") ?? res.headers.get("RateLimit-Reset") ?? 1);
await new Promise((r) => setTimeout(r, wait * 1000));
return call(url, init, attempt + 1);
}守るべき 2 つのルール:
- 絞られる前にペースを落とす。 すべてのレスポンスで
RateLimit-Remainingを読み、0に近づくにつれて速度を落としてください。429を待ってから調整を始めると、すべてのワーカーが同時に 1 往復を無駄にします。 Retry-Afterに従う。 リミッターが実際に必要とする待機時間です。推測するとたいてい悪化します。ヘッダーがない場合はRateLimit-Resetを使ってください。429の後に並列度を上げても効果はありません。制限はキー単位です。
上限の引き上げ
制限はキー単位で設定されるため、上限の引き上げはプランの変更ではなく設定変更です。ワークスペース ID、実行している Skill または操作、おおよその QPS を添えて support@unifapi.com までご連絡ください。