クレジットとレート制限

AstroWayは、単純なリクエストカウンターではなく、クレジットモデルを使用している。

これはより公平だ。軽いエンドポイント（/planets）は10クレジット、重いエンドポイント（/rectification）は500クレジットかかる。

2種類の制限

1. 日次/月次クレジット予算

月間のクレジット数はプランによって異なる：

プラン	クレジット/月	日次制限
Free	10,000	約333
Indie	50,000	約1,667
Starter	200,000	約6,667
Pro	800,000	約26,667
Business	3,500,000	約116,666
Enterprise	Custom	Custom

クレジットが使い果たされると、それ以降のリクエストは402 Payment Required（Freeプラン）を返すか、超過料金請求（Indie+プラン）が開始される。

2. レート制限 (1分あたりのリクエスト数)

プラン	RPM
Free	10 req/min
Indie	30 req/min
Starter	120 req/min
Pro	400 req/min
Business	1,000 req/min
Enterprise	Custom

レート制限はスライディングウィンドウだ。もし君が10秒間に120リクエストを送信した場合、そのキーでは次の50秒間429が返される。

もしキーに許可されたオリジンのリストがある場合、リストの各エントリがこの制限の独自のシェアを受け取る。キーの制限はエントリの数で割られ、切り上げられる。これにより、埋め込みウィジェットを持つ1つのサイトが、キーの所有者が支払っているクォータを使い果たし、他のドメインが機能しなくなるという事態を防ぐ。キーの全体的な制限は増加せず、シェアがそれを分割するだけで、追加されるわけではない。

カウンターは、アクセス元のホストではなく、エントリごとに管理される。*.example.comというエントリは、すべてのサブドメインに対して1つのカウンターを持つ。そうでなければ、リクエストごとに新しいサブドメインを作成することで制限が回避されてしまうだろう。リストに1つのエントリしかない場合、シェアは制限と同じになり、何も変わらない。

3. 公開エンドポイント (キーなし)

14のリファレンス辞書/v1/reference/*（signs, planets, houses, aspects, elements, modalities, polarities, dignities, decans, nakshatras, lots, asteroids, zodiac-systems, glyphs）は、X-Api-Keyなしで公開されており、0クレジットかかる。制限は1つのIPアドレスから1時間あたり30リクエストだ。これらのデータは、LLMエージェント向けにMCPリソースastroway://reference/<slug>としても公開されている。

同じ制限が、他の公開ネームスペース/v1/public/*、/v1/embed/*、/v1/i18n/*にも適用される。

サーバーサイドレンダリングのクォータ

1時間あたり30リクエストはブラウザ向けに設計されている。各訪問者が独自のIPとクォータをもたらすからだ。しかし、もし君のサーバー（WordPressプラグイン、SSR、キャッシュウォームアップ）がリクエストを行う場合、1つのアドレスがすべての訪問者の代わりになり、数回のページ再読み込みで制限を使い果たしてしまう。

この場合、サイトのアドレスを含むX-AstroWay-Site-URLヘッダーを送信してくれ：

X-AstroWay-Site-URL: https://example.com/

モード	制限
ヘッダーなし	IPあたり1時間あたり30リクエスト。`/v1/embed/*`ウィジェットはIPあたり1時間あたり120リクエストの個別の制限を持つ。
ヘッダーあり	サイトあたり1時間あたり300リクエスト、IPあたり1時間あたり600リクエストの天井。

このヘッダーはCORSで許可されており、認証情報ではないため、IPあたりの天井は残る。1つのアドレスからいくつのドメインが指定されても、そこから合計で1時間あたり600リクエスト以上は送信されない。両方のカウンターが同時に必要だ。サイトカウンターは、1つのサイトが複数のアドレス（CDN、ロードバランサー）からアクセスする場合に作動し、IPカウンターは、1つのアドレスから多くの名前がアクセスする場合に作動する。

1つの呼び出しが常に1単位とは限らない。 重い公開エンドポイントは、同じバケットからより多くを消費し、個別のバケットを受け取るわけではない。POST /v1/public/synastryは、2つのチャートと45セルのアスペクトマトリックスであるため、3クレジットかかる。これに対する実用的な天井は、未申告のアドレスからは1時間あたり10回、申告されたサイトからは100回、アドレスからは200回だ。その他はすべて1クレジットかかる。呼び出しが1単位以上かかる場合、応答はX-RateLimit-Costヘッダーでそれを伝え、バケットに残っている量よりも多くかかる呼び出しは、マイナスになるのではなく拒否される。

現在最も厳しいカウンターはどれか、応答ヘッダーX-RateLimit-Scope（ipまたはsite）が伝える。他のX-RateLimit-*ヘッダーはそれだけを記述する、つまり2つのカウンターのうち1つだけだ。2つ目はX-RateLimit-Countersで見ることができる：

X-RateLimit-Scope: site
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 297
X-RateLimit-Counters: ip=597/600, site=297/300

フォーマットはカンマ区切りのscope=残り/制限だ。このヘッダーは、実際に2つのカウンターがある場合、つまりX-AstroWay-Site-URLからの匿名呼び出しの場合にのみ送信される。有料キーでの呼び出しは、キーと君の料金プランに基づいてカウントされるため、カウンターは1つしかなく、このヘッダーは送信されない。もし君が1つのアドレスから複数のドメインをサーバーサイドレンダリングしているなら、これを読んでくれ。各ドメインのサイトバケットはそれぞれ異なるが、IPの天井は共通であり、それが最初に上限に達するからだ。

君の側で応答をキャッシュしてくれ。日ごとのホロスコープは1日を通して変化しないため、真夜中までのキャッシュは制限の問題を完全に解消する。

公開エンドポイントでの有料キー。 /v1/public/*および/v1/embed/*はキーなしで動作するが、もし君がX-Api-Keyを渡した場合、リクエストは匿名クォータではなく君の料金プランに基づいてカウントされ、応答には無料の透かしがない。これはサーバーサイドレンダリングに意味がある。1台のマシンがすべての訪問者の代わりになり、匿名300/時間では彼女には少ないからだ。

料金表

すべての771以上のエンドポイントとその料金を含む完全な透明な表は、エンドポイント料金ページにある。DivineAPI/AstrologyAPI/Prokeralaはこのような表を公開していない。簡単な目安は以下の通りだ：

Tier	クレジット	標準時間	例
1	10	< 50 ms	`/planets`, `/moon-voc`, `/iching`
2	20	50–200 ms	`/chart`, `/harmonics`, `/horary`
3	50	200–500 ms	`/synastry`, `/progressions`, `/acg`
4	100	> 500 ms	`/transit-calendar`, `/forecast-calendar`
5	250	数秒	`/rectification/trutine`
6	500	最大120秒	`/rectification`

応答ヘッダー

各応答には以下が含まれる：

X-Credits-Used: 20
X-Credits-Remaining: 9980
X-Credits-Limit: 10000
X-Credits-Reset: 2026-05-01T00:00:00Z
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118
X-RateLimit-Reset: 1714521600
X-RateLimit-Origin-Limit: 60
X-RateLimit-Origin-Remaining: 59
X-Request-Id: 8aec43e9bc749b37e998a489bbad1757

X-Credits-Used: このリクエストで消費されたクレジット数
X-Credits-Remaining: 月間予算の残りクレジット数
X-Credits-Limit: 月間のクレジットの全予算（プランによる）
X-Credits-Reset: 残高更新のISO-8601形式の日付
X-RateLimit-*: スライディングウィンドウの現在の状態（標準フォーマット）
- X-RateLimit-Scope: 現在最も厳しいカウンターはどれか：ip、site、またはkey。keyの値は、リクエストが君のキーと君の料金プランの制限に基づいてカウントされ、匿名クォータではないことを意味する。
- X-RateLimit-Counters: X-AstroWay-Site-URLで呼び出された公開エンドポイントで、リクエストがカウントされたすべてのカウンターがscope=残り/制限のフォーマットで表示される。上記のヘッダーは最も厳しいもののみを記述する。
- X-RateLimit-Reset: 最も古いリクエストがウィンドウから外れる瞬間、つまり1つのスロットが解放されるとき。これはバケットが完全に開く時間ではない。その後1つのリクエストが通過すると、Resetは次の時間へとずれる。Resetまで待ってから一括送信するクライアントは、再び429を受け取るため、1つずつリクエストを送信するか、君の側で応答をキャッシュする方が確実だ。
- 拒否されたリクエスト（429）はクォータを消費せず、ウィンドウをずらさない。カウンターは成功したリクエストでのみ補充される。
- X-RateLimit-Origin-LimitおよびX-RateLimit-Origin-Remaining: リクエストが許可されたオリジンのリストのエントリを通過した場合にのみ送信され、そのエントリに割り当てられたシェアを示す。このシェアによる拒否も429であり、テキストにはどのエントリが使い果たされたかが記載されている。
X-Subscription-StatusおよびX-Subscription-Grace-Ends: 有料期間がすでに終了しているが、3日間の猶予期間がまだ続いている場合（X-Subscription-Status: grace）にのみ送信される。リクエストはX-Subscription-Grace-Endsに記載された時点まで君の料金プランに基づいて処理され、その後、応答は402 SUBSCRIPTION_EXPIREDとなる。もし君のクライアントがヘッダーをログに記録するなら、これはプランを更新すべきであるという最も早い信号だ。
X-Request-Id: リクエストID、32桁の16進数。サポートに連絡する際にそれを伝えてくれ。

すでにいくら消費されたか：3つの方法

現在のクレジット残高は3つの方法で確認できる。最も速いものから最も詳細なものまで：

各応答で: X-Credits-Remaining / X-Credits-Used / X-Credits-Limitヘッダーは、どんなリクエスト（エラーに対しても）に対しても返される。追加で何かを呼び出す必要はない。残高は常に目の前にある。
個別のリクエストで: 君のX-Api-Keyを使ってGET /v1/keys/usageを呼び出すと、credits（used / remaining / limit / reset）、usage（today / week / monthのリクエスト数）、および30日間のトップ20エンドポイントが返される。1回の呼び出しで、個別の管理者キーは不要だ。
ダッシュボードで: api.astroway.info/dashboard/billingは、残高、使用状況グラフ、エンドポイントごとの内訳をリアルタイムで表示する。

curl https://api.astroway.info/v1/keys/usage \
  -H "X-Api-Key: $AW_KEY"

キャッシュ

5分以内の同一のリクエストは、クレジットを消費せずにキャッシュから返される。これは個別のヘッダーだ：

X-Cache: HIT
X-Credits-Used: 0

「同一」と見なされるもの：

同じエンドポイント
同じJSONボディ（スペース正規化後、バイト単位で完全に一致）
同じAPIキー

すべてのエンドポイントは決定論的であるため、これは安全だ。同じ入力は常に同じ出力を生成する。

ストリーミングとウェブフック

ストリーミング (`/stream/*`)

10のストリームエンドポイントは、Tier 1: 1呼び出しあたり10クレジットとして課金される。各呼び出しは惑星の位置を再計算するため、これは完全な計算であり、キャッシュされたルックアップではない。ティックごとの「より安い」料金設定はない。

各応答には、効率的なポーリングのための2つのフィールドが含まれる：

tickSeconds: 推奨されるポーリング間隔
nextEventAt: 次に状態が変化する時

tickSecondsよりも頻繁にポーリングするのは、クレジットを無駄に消費するだけだ。状態はnextEventAtまで変化しない。

ウェブフック (`/webhooks/*`)

サブスクリプション管理のCRUD操作（/webhooks/subscribe、リスト、表示、削除、/test）は、それぞれTier 1: 10クレジットかかる。これらはまれな呼び出しだ。

イベント配信（サーバー → 君のURL）は課金されない。クレジットは管理のCRUD呼び出しに対してのみ消費される。12種類のイベントタイプ（report-ready、transit-alert、eclipse-alert、dasha-change、sign-ingressなど）がサポートされている。

ウェブフックはProプラン以上で利用可能だ。

制限を超過した場合の対処法

`402 Payment Required`: クレジットがなくなった

{
  "error": {
    "code": "credits_exhausted",
    "message": "Monthly credit budget exhausted. Upgrade plan or wait for reset.",
    "credits_remaining": 0,
    "credits_reset": "2026-05-01T00:00:00Z",
    "upgrade_url": "https://api.astroway.info/dashboard/billing"
  }
}

オプション：

プランのアップグレード: すぐに新しい予算を受け取る
超過料金 (Starter/Pro): 設定で無効にされていない限り自動的に有効になる
リセットを待つ (Free): 翌月の1日

`429 Too Many Requests`: RPMを超過した

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Retry after 12 seconds.",
    "retry_after_seconds": 12
  }
}

Retry-After: 12ヘッダーは標準的なHTTPヘッダーであり、君のHTTPクライアントはそれを理解する必要がある。

正しい処理:

async function callWithRetry(endpoint: string, body: object) {
  const response = await fetch(endpoint, {
    method: 'POST',
    headers: { 'X-Api-Key': key, 'Content-Type': 'application/json' },
    body: JSON.stringify(body),
  });

  if (response.status === 429) {
    const retryAfter = Number(response.headers.get('Retry-After') ?? 1);
    await new Promise((r) => setTimeout(r, retryAfter * 1000));
    return callWithRetry(endpoint, body);
  }

  return response.json();
}

事前の予算見積もり

統合前に、月にいくつのクレジットが必要か見積もってくれ：

monthly_credits = daily_active_users × calls_per_user × avg_cost_per_call × 30

例：500DAUのアプリケーションで、各ユーザーが1日に3回のチャート計算 + 1回のシナストリーを行う場合：

500 × (3 × 20 + 1 × 50) × 30 = 500 × 110 × 30 = 1,650,000 credits/mo
→ Enterprise (custom)

予算計算ツールは料金ページにある。

次に

エラー: エラーコードの完全なリファレンス
冪等性: 安全にリクエストを再試行する方法

参考になりましたか？

編集を提案

最終更新日: 2026/10/05