◉CLAUDE LABEN
●BILLING — 11/17 に Linked billing がベータ公開。顧客が自分の Claude 組織をつなぐと、リクエストごとに支払元を選べます●CC 2.1.326 — Claude Code 2.1.326(11/16)で、書き方が不完全な --allowedTools のルールに起動時の警告が出るようになりました●SONNET 4.5 — Claude API での提供終了は 11/30、残り12日。コードと保存済みのモデル設定を一度に洗い出してください●PARALLEL — 並列のセッションを一晩回したら週の利用枠の約7割が消えた、という報告が出ています●CREDIT — 「Credit balance is too low」は、自分の組織・顧客の組織・プランのどれの残高かを先に確かめると早く片づきます●NEW — 定期実行は1日の回数と1回の量を掛けてから組む●BILLING — 11/17 に Linked billing がベータ公開。顧客が自分の Claude 組織をつなぐと、リクエストごとに支払元を選べます●CC 2.1.326 — Claude Code 2.1.326(11/16)で、書き方が不完全な --allowedTools のルールに起動時の警告が出るようになりました●SONNET 4.5 — Claude API での提供終了は 11/30、残り12日。コードと保存済みのモデル設定を一度に洗い出してください●PARALLEL — 並列のセッションを一晩回したら週の利用枠の約7割が消えた、という報告が出ています●CREDIT — 「Credit balance is too low」は、自分の組織・顧客の組織・プランのどれの残高かを先に確かめると早く片づきます●NEW — 定期実行は1日の回数と1回の量を掛けてから組む
記事一覧/API & SDK
⬡ API & SDK/2026-11-18中級

Linked billing で顧客に払ってもらう前に — 402 と 403 が返ったとき、どの財布が空なのかを見分ける

11月17日にベータ公開された Claude API の Linked billing では、リクエストごとに billing_policy で支払元を選べます。顧客に請求したリクエストが 402 や 403 で拒まれたとき、どの財布が原因かを切り分け、自分の負担で返すかを決める手順と、Python のラッパーをまとめました。

Claude API148Linked billingbilling_policy課金7エラー処理3cost5

11月18日の朝、Platform のリリースノートに Linked billing のベータ公開が載っているのを見つけて、コーヒーを淹れる手が止まりました。アプリの利用者が、自分の Claude 組織で API 代を払えるようになる仕組みです。

個人開発で AI を使う機能を考えるたびに、私はいつも同じところで立ち止まっておりました。利用者が増えるほど、API の請求は私ひとりの財布に積み上がります。その不安を、仕組みの側で分け持ってくれるかもしれない——そう思って、ドキュメントを最後まで読みました。

最初にお伝えしたいのは、Linked billing を入れると、「Credit balance is too low」に相当するエラーの持ち主が二人になるという点です。自分の組織の残高なのか、顧客の組織の残高や上限なのか。ここを取り違えると、顧客に「お支払いを確認してください」と書いた通知を、実は自分の設定ミスで出してしまいます。

私はまだ本番の顧客をつないではいません。ここに書くのは、公式ドキュメントを読み、テスト用の手元コードを組みながら整理した、拒否されたときの見分け方です。

Linked billing は何を変えるのか

公式ドキュメント「Linked billing」によると、流れは次のとおりです。

  1. 顧客が、あなたのアプリの「Link your Claude organization」ボタンから OAuth で自分の Claude 組織をつなぎます(つなぐ人は顧客側で Admin か Billing のロールが必要です)
  2. あなたは自分の組織に、顧客を表す user profile を作っておきます
  3. リクエストごとに、本文の 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 に入ります。

HTTPerror_code空いているのは誰の何か再試行
402linked_organization_spend_limit_reached顧客側。あなたのアプリに設定された上限、組織全体の月間上限、または支払いに使えるクレジットがない。どれかは返ってきませんしない
402linked_organization_billing_unavailable顧客側。組織の停止や、応答の途中でクレジットが尽きた場合などしない
403user_profile_not_billableあなた側の可能性が先。認証の種類、ヘッダーの profile ID、接続が切れていないか。顧客の組織が対象外の場合もあります接続直後の10秒以内だけ
400user_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 が、自分のコードのどの分岐に落ちるかを一度見ておけば、本番で慌てずに済むはずです。

顧客の財布と自分の財布の境目を、コードの一か所にだけ置いておく——この原則は、ベータの仕様が変わっても手放さないつもりでおります。

シェア

お読みいただきありがとうございます

Claude Lab は広告なしで運営しており、サーバー費用などの運営コストはメンバーシップのご支援で賄っています。実装コード・ベンチマーク・本番設計パターンなど、実務でお役立ていただける記事を毎日更新しています。もし読んでよかったと感じていただけましたら、ぜひご覧ください。

  • ✦コピー&ペーストで使える実装コード付き
  • ✦毎日新しい上級ガイドを追加
  • ✦¥580/月 または ¥1,480 の永久アクセス
メンバーシップを見る →

もしこの記事がお役に立ちましたら、チップ(¥150)で応援いただけると大変励みになります。広告なしでの運営を続けるため、皆さまのご支援が大きな力になっています。

関連記事

⬡ API & SDK2026-10-22
上限に達したのに 400 が返ってきた — 自分で決めた利用上限・階層の月間上限・レート制限を見分ける
Claude API の「上限」系エラーは3種類あり、ステータスも待てば直るかどうかも違います。自分で設定した上限は400、階層の月間上限は429、通常のレート制限も429。見分けるコードと判断表をまとめました。
⬡ API & SDK2026-04-06
Claude の課金エラー対処:「Credit balance is too low」・支払い拒否・プラン未反映の切り分け
Claude API の「Credit balance is too low」、Pro/Max の支払い拒否、プランが反映されない、身に覚えのない請求。症状ごとに確認する順番を、個人でアプリを運営してきた立場から整理しました。
⬡ API & SDK2026-11-17
テキスト透かしを当てにするなら、コードではなく送信ボディで temperature を確かめます
11月16日から Opus 4.6・Opus 4.5・Sonnet 4.5・Haiku 4.5 の出力にもテキスト透かしが入ります。temperature・top_p・top_k を既定以外にすると付かない場合があるため、実際に送られたボディを1回だけ記録して判断する手順をまとめました。