11月18日の朝、Platform のリリースノートに Linked billing のベータ公開が載っているのを見つけて、コーヒーを淹れる手が止まりました。アプリの利用者が、自分の Claude 組織で API 代を払えるようになる仕組みです。
個人開発で AI を使う機能を考えるたびに、私はいつも同じところで立ち止まっておりました。利用者が増えるほど、API の請求は私ひとりの財布に積み上がります。その不安を、仕組みの側で分け持ってくれるかもしれない——そう思って、ドキュメントを最後まで読みました。
最初にお伝えしたいのは、Linked billing を入れると、「Credit balance is too low」に相当するエラーの持ち主が二人になるという点です。自分の組織の残高なのか、顧客の組織の残高や上限なのか。ここを取り違えると、顧客に「お支払いを確認してください」と書いた通知を、実は自分の設定ミスで出してしまいます。
私はまだ本番の顧客をつないではいません。ここに書くのは、公式ドキュメントを読み、テスト用の手元コードを組みながら整理した、拒否されたときの見分け方です。
Linked billing は何を変えるのか
公式ドキュメント「Linked billing」によると、流れは次のとおりです。
- 顧客が、あなたのアプリの「Link your Claude organization」ボタンから OAuth で自分の Claude 組織をつなぎます(つなぐ人は顧客側で Admin か Billing のロールが必要です)
- あなたは自分の組織に、顧客を表す user profile を作っておきます
- リクエストごとに、本文の
billing_policyでbill_to: "user_profile"(顧客が払う)かbill_to: "self"(自分が払う)を選びます
顧客に払ってもらうリクエストには、ベータヘッダー user-profiles-billing-2026-10-01 と、anthropic-user-profile-id ヘッダーが要ります。対象は /v1/messages と /v1/chat/completions で、Message Batches はまだ顧客への請求に対応していません。
見落としやすいのは、リクエストはあくまで自分の組織で動くという点です。レート制限、使えるモデル、データの保持期間は、あなたの組織の設定が適用されます。顧客側で結んでいるゼロデータ保持(ZDR)や BAA は、このリクエストには及びません。
顧客の財布に入っていても、払えないお金があります
ドキュメントの「Which credits can pay」の節で、私は二度読み返しました。顧客に請求するリクエストを払えるのは、Console で購入したクレジットか、請求書払いの契約だけです。
Max・Ultra・Team プランに毎月付く API クレジットは、この支払いに使えません。スタートアップ支援や VC 経由のクレジットも対象外です。顧客から見れば「残高はある」のに、あなたのアプリ経由の呼び出しは拒否される——以前「Credit balance is too low の前に見る3つの勘定」で書いた、財布が分かれている問題が、ここでも顔を出します。
さらに、AWS・Google Cloud・Azure のマーケットプレイス経由で払っている組織と、Claude のサブスクリプションしか持たない組織は、そもそもつなげても請求できません。これは 403 user_profile_not_billable で拒否されます。
拒否されたとき、どの財布かを見分ける表
Linked billing の良いところは、顧客に請求できなかった分を、黙ってあなたに付け替えないことです。かならず拒否として返ってきます。/v1/messages では、理由のコードが error.details.error_code に入ります。
| HTTP | error_code | 空いているのは誰の何か | 再試行 |
|---|---|---|---|
| 402 | linked_organization_spend_limit_reached | 顧客側。あなたのアプリに設定された上限、組織全体の月間上限、または支払いに使えるクレジットがない。どれかは返ってきません | しない |
| 402 | linked_organization_billing_unavailable | 顧客側。組織の停止や、応答の途中でクレジットが尽きた場合など | しない |
| 403 | user_profile_not_billable | あなた側の可能性が先。認証の種類、ヘッダーの profile ID、接続が切れていないか。顧客の組織が対象外の場合もあります | 接続直後の10秒以内だけ |
| 400 | user_profile_required | あなた側。bill_to: "user_profile" なのに profile ID ヘッダーがない | 直してから |
| 503 | (overloaded_error) | 誰でもない。請求できるか確認できなかっただけで、請求もされていません | する(retry-after に従う) |
私が最初に勘違いしたのは 403 でした。名前から「顧客が払えない」と読んでしまいそうですが、ドキュメントの確認順はまず自分のリクエストです。operator に指定したサービスアカウント以外で認証していたり、つながっていない profile の ID を送っていたりすると、同じコードが返ります。顧客に連絡するのは、自分の側を確かめたあとです。
失敗から引いた線引き
テストのつもりで組んだ最初のラッパーは、402 も 403 も区別せず、すべて bill_to: "self" で送り直していました。利用者の体験は途切れません。その一方で、顧客の上限に当たった月は、上限を超えた分がそっくり私の請求に乗ることになります。
上限は顧客が自分で決めた金額です。いま思えば、最初のラッパーは「利用者を待たせない」ことだけを見ていて、誰の判断を上書きしているのかを考えていなかったのかもしれません。それを私が黙って肩代わりすれば、顧客が上限を置いた意味がなくなりますし、私の財布にも底がありません。そこで、次のように分けることにしました。
上限に当たったら止めて知らせ、仕組みの不調なら私が払って続ける。
具体的には、spend_limit_reached は顧客へ「Console の Linked platforms でこのアプリの上限を確認してください」と伝えて止めます。billing_unavailable と、自分の側の原因を確かめ終えた not_billable は、件数に上限を置いたうえで bill_to: "self" にして続けます。
判定を一か所にまとめるラッパー
下のコードは、顧客に請求するリクエストを送り、拒否されたら理由を分類して、肩代わりするかどうかを返すものです。テスト用の組織で書いた叩き台で、本番の顧客には向けておりません。
import anthropic
BILLING_BETA = "user-profiles-billing-2026-10-01"
BILL_CUSTOMER = {"type": "billing_policy", "bill_to": "user_profile"}
BILL_SELF = {"type": "billing_policy", "bill_to": "self"}
# 顧客側の上限は肩代わりしない。仕組み側の不調だけ自分で払って続ける
STOP_AND_NOTIFY = {"linked_organization_spend_limit_reached"}
FALLBACK_TO_SELF = {"linked_organization_billing_unavailable", "user_profile_not_billable"}
def error_code_of(err: anthropic.APIStatusError) -> str | None:
body = err.body if isinstance(err.body, dict) else {}
return (body.get("error") or {}).get("details", {}).get("error_code")
def create_for_customer(client, profile_id, messages, model, self_budget):
"""self_budget は今月まだ肩代わりしてよい回数。呼び出し側で数を持つ"""
params = dict(model=model, max_tokens=1024, messages=messages, betas=[BILLING_BETA])
try:
msg = client.beta.messages.create(
**params,
extra_headers={"anthropic-user-profile-id": profile_id},
extra_body={"billing_policy": BILL_CUSTOMER},
)
return {"message": msg, "billed_to": "customer"}
except anthropic.APIStatusError as err:
code = error_code_of(err)
if err.status_code == 503:
raise # SDK の自動再試行でも通らなかった分。請求はされていない
if code in STOP_AND_NOTIFY:
return {"message": None, "billed_to": None, "notify": "customer_spend_limit"}
if code in FALLBACK_TO_SELF and self_budget > 0:
msg = client.beta.messages.create(**params, extra_body={"billing_policy": BILL_SELF})
return {"message": msg, "billed_to": "self", "reason": code}
return {"message": None, "billed_to": None, "notify": code or f"http_{err.status_code}"}なぜこう書くのか、二点だけ補足します。
一つ目は、billed_to を自分で返していることです。成功した応答には、誰に請求されたかが書かれていません。ドキュメントも「どのリクエストを user_profile で送ったか、自分で記録を持つように」と書いています。月末に顧客から問い合わせが来たとき、答えられるのはこの記録だけです。
二つ目は、肩代わりのリクエストで profile ID ヘッダーを外していることです。顧客ごとに発行される接続のアクセストークンは、bill_to: "self" を送ると拒否されます。送り直しは、operator のサービスアカウント自身の資格情報で行う必要があります。上のコードの client は、その資格情報で作ったものを想定しています。
もう一つ、黙って起きるほうの事故
ドキュメントの警告の中で、いちばん背筋が冷えたのはここでした。operator の資格情報は、このアプリにつながっているすべての顧客に請求できます。ヘッダーの profile ID を別の顧客のものと取り違えると、エラーにならず、その別の顧客に請求されます。
拒否は表で見分けられますが、取り違えは何も教えてくれません。私は、profile ID をリクエストの直前に引くのをやめ、顧客のレコードとセットで渡す形にしました。顧客ごとに一つのトークンで済むなら、その顧客にしか請求できない接続のアクセストークンを使うほうが、事故の幅は小さくなります。
上限が戻るのはいつか
顧客がアプリに設定する月の上限は米ドル建てで、上限に当たると 402 が続きます。戻るのは翌月1日の 00:00 UTC か、顧客が上限を上げるか外したときです。日本時間では1日の朝9時にあたります。上限の変更が反映されるまでには1分ほどかかるとされています。
あなたの側から、顧客の上限額や使用額は読めません。ですから通知の文面は「上限に達しました」と断定せず、「上限、月間の支出上限、クレジット残高のいずれかをご確認ください」と三つを並べておくのが、いまの仕様ではいちばん正直だと思います。支払い全般の切り分けは「Claude の課金エラー対処」に、利用量に応じた請求の組み方は「Claude API を組み込んだ B2B SaaS の従量課金」にまとめています。
次の一手
まずは自分の別の組織をテスト用の顧客としてつなぎ、このアプリへの上限を 0 ドルに設定してみてください。0 ドルの上限は、顧客に請求するリクエストをすべて拒否します。そこで返ってくる 402 が、自分のコードのどの分岐に落ちるかを一度見ておけば、本番で慌てずに済むはずです。
顧客の財布と自分の財布の境目を、コードの一か所にだけ置いておく——この原則は、ベータの仕様が変わっても手放さないつもりでおります。