Credits abrufen
Lies den Credit-Stand, den dieser API-Key ausgeben kann.
usage.read Scope. Für Preisdetails siehe
Preise.
Credential-verfügbar vs. organisationsweit
Die Antwort enthält zwei Arten von Zahlen.available und spendable_plan_credits
beantworten „was kann dieses Credential ausgeben“; plan_credits und topup_credits
sind organisationsweite Stände.
available == spendable_plan_credits + topup_creditsspendable_plan_credits <= plan_credits- für eine Organisation ohne aktive Teams gilt
spendable_plan_credits == plan_credits
scope.type
ist org, spendable_plan_credits entspricht plan_credits, und available ist
weiterhin der Plan-Pool plus Top-ups.Das Budget-Regime (scope)
Eine Organisation kann Teile ihres monatlichen Plan-Pools als Budgets pro Team
reservieren, und jeder API-Key kann einem Team zugewiesen werden. Ein Credential gibt
dann aus genau einem Bucket aus, und nur der Spielraum dieses Buckets steht ihm zur
Verfügung — deshalb kann available niedriger sein als die organisationsweiten
plan_credits.
scope.team nennt das Team, dem das Credential zugewiesen ist, oder ist null, wenn es
keinem zugewiesen ist. scope.remaining ist budget - used, nach unten auf 0 begrenzt.
Ein team-gebundener Key, bei dem das Budget die begrenzende Größe ist:
8031 Plan-Credits, aber vom Marketing-Budget sind 1200
übrig — dieser Key kann also nur 1200 davon ausgeben, plus die 250 von Budgets
ausgenommenen Top-up-Credits, insgesamt 1450.
Ein 402 vorhersagen und diagnostizieren
available ist die Vorhersage. Ein Job, dessen estimated_credits höchstens
available betragen, wird nicht mit einem Credit-402 abgelehnt, und umgekehrt bedeutet
so ein 402, dass die Schätzung available überschritten hat — bei beidem die Zahl
des Credentials, nicht die der Organisation. Eine Ausnahme: ein operativer Fehler in
der Abbuchung selbst (etwa eine gestörte Saldo-Abfrage) wird unabhängig vom Regime als
generisches insufficient_credits gemeldet,
ohne etwas über available zu beweisen — ein schlichtes insufficient_credits, wo du
einen team-spezifischen Code erwartet hättest, kann also vorübergehend sein; versuche es
erneut, bevor du es als erschöpften Stand behandelst.
Wenn ein Absenden abgelehnt wird, erklärt scope es:
scope.typenennt das Budget-Regime, und das wählt den Fehlercode aus (abgesehen vom operativen Fallback oben) — siehe die Tabelle oben. Es sagt dir nicht, welcher Stand erschöpft war: ein Key imteam-Regime erhältinsufficient_team_creditsauch dann, wenn der Plan-Pool der Organisation und nicht das Team-Budget aufgebraucht war.- Um unter einem begrenzten Regime (
teamoderunallocated) die tatsächliche Ursache zu finden, vergleicheplan_creditsmitscope.remaining— der kleinere Wert begrenztspendable_plan_credits. Unterorgistscope.remainingnullundplan_creditsist die einzige mögliche Ursache. remaining: 0bedeutet, dass dieser Bucket für die aktuelleperiodvollständig ausgegeben ist. Es ist keine Voraussetzung für den Fehler: ein Bucket mitremaining: 100und ohne Top-ups lehnt einen Job für200weiterhin ab.
available: 0 mit scope.type: "unallocated" und remaining: 0 — jedes
Absenden, das Credits kostet, wird mit insufficient_unallocated_credits abgelehnt, bis ein Budget gesenkt
wird, der Key einem Team mit Spielraum zugewiesen wird oder Top-ups gekauft werden. Siehe
Fehler für den Umgang mit jedem Code.Autorisierungen
Organization API key as a bearer token: Authorization: Bearer samsa_sk_....
Antwort
Successful Response
GET /credits body — what the CALLING credential can spend (ADR §10, SAM-1029).
Two kinds of number:
available/spendable_plan_creditsanswer "what can THIS API key or OAuth connection spend right now" — capped by its team budget bucket (scope), so a job estimated at or belowavailableis not rejected withinsufficient_team_credits/insufficient_unallocated_credits.plan_credits/topup_creditsare the ORGANIZATION-wide balances.
All amounts are balances (not allocations), and
available == spendable_plan_credits + topup_credits always holds, as does
spendable_plan_credits <= plan_credits (they are equal whenever no team
budget applies).
Total credits the calling credential can spend right now — the sum of spendable_plan_credits and topup_credits. Capped by the credential's team budget bucket (see scope), so it can be lower than the organization-wide plan_credits.
1450
Plan-pool credits the calling credential can spend right now: plan_credits capped by scope.remaining. Equal to plan_credits when no team budget applies.
1200
The ORGANIZATION's remaining monthly subscription-pool credits — not necessarily all spendable by this credential (see spendable_plan_credits). 0 when the plan pool is exhausted or the subscription is canceled and past its period end (top-up credits stay spendable).
1200
Remaining credits from valid (non-expired) top-up purchases. Top-ups are exempt from team budgets, so they are always fully spendable by any credential of the organization.
250
The org subscription's current billing-period bounds (ISO-8601).
The credit bucket the calling credential spends from (SAM-1029).
Organizations can reserve parts of their monthly plan pool for teams. A
credential (API key or OAuth connection) spends from exactly ONE bucket, and
only that bucket's headroom is available to it — which is why available
can be lower than the organization-wide plan_credits. The shortfall rule
is cost > available (spendable_plan_credits + topup_credits): a submit
is refused with an insufficient-credit 402 when the deduction,
re-evaluating the same numbers at execution time, finds the estimated cost
above available — insufficient_credits under the uncapped org regime,
insufficient_team_credits under team, and
insufficient_unallocated_credits under unallocated (operational
failures inside the deduction fall back to the generic
insufficient_credits, whatever the regime). This response is a
point-in-time snapshot, not a reservation: concurrent spends, top-up lots
expiring, a canceled subscription's period ending, or a degraded balance
lookup can make the deduction-time numbers differ from the ones reported
here, and other checks can reject a request regardless of credits.
type names the budget regime and selects which of those codes a balance
shortfall raises — it does not say which balance ran out: under a capped
regime the smaller of plan_credits and remaining limits
spendable_plan_credits.
remaining: 0 means this bucket has no plan-pool headroom left for the
current period (spent down, or never allocated any); it is NOT a
precondition of the error — a bucket with remaining: 100 and no top-ups
still refuses a job costing 200.

