レート制限

最終更新 July 20, 2026

API は API キーごとにレート制限される(認証のないリクエストではクライアント IP にフォールバックする)。Suede が制限値とウィンドウを定め、それらを変更することがあるため、数値をハードコードするのではなく、レスポンスヘッダーから読み取ること。

ヘッダー

すべての /v1 レスポンスには次が含まれる:

ヘッダー	意味
`X-RateLimit-Limit`	現在のウィンドウで許可される最大リクエスト数。
`X-RateLimit-Remaining`	現在のウィンドウで残っているリクエスト数。
`X-RateLimit-Reset`	ウィンドウがリセットされる Unix エポック秒。

制限を超えると、API は HTTP 429 と Retry-After ヘッダー(待つべき秒数)で応答する:

JSON

{ "error": { "type": "rate_limited", "message": "Rate limit exceeded. Slow down and retry after the reset.", "request_id": "…" } }

429 の扱いかた

Retry-After の秒数だけ待ってから再試行する。単純で信頼できるパターン:

cURL

# 任意のレスポンスのヘッダーから、現在の使用枠を確認する。
curl -sD - -o /dev/null "https://api.suede.io/v1/search?q=test" \
  -H "Authorization: Bearer $SUEDE_API_KEY" | grep -i '^x-ratelimit'

async Task<HttpResponseMessage> GetWithRetryAsync(HttpClient http, string url)
{
    while (true)
    {
        var res = await http.GetAsync(url);
        if (res.StatusCode != System.Net.HttpStatusCode.TooManyRequests) return res;
        var wait = res.Headers.RetryAfter?.Delta ?? TimeSpan.FromSeconds(1);
        await Task.Delay(wait);
    }
}

JavaScript

async function getWithRetry(url, init) {
  for (;;) {
    const res = await fetch(url, init);
    if (res.status !== 429) return res;
    const wait = Number(res.headers.get("retry-after") ?? "1") * 1000;
    await new Promise((r) => setTimeout(r, wait));
  }
}

レート制限は課金とは別である。メンバーシップが無効であるか、クレジット残高が空のときに返される 402 レスポンスについては、エラーを参照のこと。