課金と返金
リアルタイムの課金はプロダクト単位、識別子単位です。呼び出しは最初に金額を予約し、選択したすべてのプロダクトの結果が出た時点で確定します。
予約してから確定
Section titled “予約してから確定”呼び出しが受け付けられると、プラットフォームは選択されたプロダクトの1チェックあたりの価格の合計を予約します。この時点ではまだ課金されません。結果が返るにつれて、各エントリが個別に確定します。
- charged のエントリは予約を維持します
- refunded のエントリは予約額を残高に戻します
レスポンス内の3つの合計がその確定を表します。
| フィールド | 意味 |
|---|---|
total_reserved | 呼び出しが受け付けられた時点で予約された額 |
total_charged | 実際に保持された額 |
total_refunded | 残高に戻された額 |
これらは常に釣り合います。total_reserved = total_charged + total_refunded。
課金されるもの、返金されるもの
Section titled “課金されるもの、返金されるもの”| 結果 | billing_status | 意味 |
|---|---|---|
valid — 識別子が登録されている | charged | 実際の回答が得られた |
invalid — 識別子が登録されていない | charged | 実際の回答が得られた |
unknown — サプライヤーが決定的な結果を返さなかった | refunded | 回答なし。決定的でない結果は課金されません |
| プロバイダーのタイムアウト | refunded | error_code: provider_timeout |
| チャネルまたはユーザースロットが利用不可 | refunded | error_code: channel_busy / user_busy |
| 共有ファクトに対する並行性保護 | refunded | error_code: fact_refresh_busy |
| サプライヤーがチェックに失敗 | refunded | error_code: realtime_failed |
| 結果キャッシュが利用不可 | refunded | error_code: fact_cache_unavailable |
キャッシュヒットでも課金されます。 cached: true のエントリは、以前のチェックで生成され保存された実際の回答です。課金は回答に対するものであり、往復に対するものではありません。返金されるのは unknown と失敗の結果のみです。
一部成功した呼び出しの読み方
Section titled “一部成功した呼び出しの読み方”各エントリは個別に確定するため、1回の呼び出しに両方の結果が含まれることがあります。これは status: partial_succeeded として報告され、HTTP は依然として 200 です。200 を「すべて成功した」と決して解釈しないでください。
statusを確認する- 各エントリについて
billing_statusとerror_codeを確認する
status の値: succeeded（すべてのエントリが課金）、partial_succeeded（混在）、failed（課金対象の回答を生成したエントリがない）。
呼び出しには予約額全体を賄える残高が必要です。不足している場合、どのプロダクトにも問い合わせる前に 402 insufficient_balance で失敗します。何も予約されず、課金もされません。
残高自体は GET /v1/balance から取得できます。アカウント残高 を参照してください。
返金リクエストの手順はありません。返金されたエントリは同じ呼び出しの一部として残高に戻され、受け取るレスポンスにはすでに最終的な数値が反映されています。