Skip to content

Build AI methods with your coding agent, then run them anywhere: as an MCP for chatbots, as a webapp for people, or via API for your software.

feature/Credit-refusal-names-ledger · L-261027-a89748 (#1501)

Louis Choquel4647d0de35d3
diff --git a/CHANGELOG.md b/CHANGELOG.md
index f3120e9f6..24c8fceb1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,11 @@
# Changelog
+## [Unreleased]
+
+### Added
+
+- **`pipelex.billing.credit_exhausted` names the credit ledger that ran out**: the code declares an optional `ledger` parameter, `inference` or `usage`, so the hosted platform's refusal of a run says whether the organization's inference credit or its usage credit is spent, and `BillingCreditExhaustedParams` gains the `ledger` field. A model call refused once the credit has run out names no ledger, as before.
+
## [v0.93.0] - 2026-10-27
### Fixed
diff --git a/docs/errors/pipelex/billing/credit_exhausted.md b/docs/errors/pipelex/billing/credit_exhausted.md
index 38e29f204..dbbbcd03c 100644
--- a/docs/errors/pipelex/billing/credit_exhausted.md
+++ b/docs/errors/pipelex/billing/credit_exhausted.md
@@ -18,7 +18,7 @@ description: "The organization is out of credit: what the Pipelex error code pip
## What it means
-The organization's credit is spent. The platform refuses a run before queueing it, and a model call made once the credit has run out is refused as well.
+The organization's credit is spent. The hosted platform keeps two credit ledgers, inference credit and usage credit, and refuses a run before queueing it while either is at zero or below, naming the ledger that refused it in `params.ledger`. A model call made once the credit has run out is refused as well, and names no ledger.
## What to do
@@ -41,7 +41,11 @@ The problem's `detail` is written from this template, filled with the occurrence
## Parameters
-This code declares no parameters, so its problems carry no `params`.
+A parameter is present on every occurrence of the code unless it is marked optional, and one marked operator-only reaches only whoever runs the runtime, never a caller.
+
+| Name | Type | Description |
+|---|---|---|
+| `ledger` | one of `inference`, `usage` (optional) | The credit ledger whose balance refused the operation: the organization's inference credit or its usage credit. |
## See also
diff --git a/pipelex/errors/registry/pipelex-error-registry.json b/pipelex/errors/registry/pipelex-error-registry.json
index 23c0cde30..f99748386 100644
--- a/pipelex/errors/registry/pipelex-error-registry.json
+++ b/pipelex/errors/registry/pipelex-error-registry.json
@@ -118,8 +118,18 @@
"detail": "Ask the account's owner to add credit to the organization."
}
},
- "params": {},
- "meaning": "The organization's credit is spent. The platform refuses a run before queueing it, and a model call made once the credit has run out is refused as well.",
+ "params": {
+ "ledger": {
+ "type": "enum",
+ "values": [
+ "inference",
+ "usage"
+ ],
+ "optional": true,
+ "description": "The credit ledger whose balance refused the operation: the organization's inference credit or its usage credit."
+ }
+ },
+ "meaning": "The organization's credit is spent. The hosted platform keeps two credit ledgers, inference credit and usage credit, and refuses a run before queueing it while either is at zero or below, naming the ledger that refused it in `params.ledger`. A model call made once the credit has run out is refused as well, and names no ledger.",
"what_to_do": "Add credit to the organization, or move it to a plan that includes more, then start the run again."
},
{
diff --git a/pipelex/errors/registry/pipelex-error-registry.yaml b/pipelex/errors/registry/pipelex-error-registry.yaml
index e3c1e24d2..9ca3410c5 100644
--- a/pipelex/errors/registry/pipelex-error-registry.yaml
+++ b/pipelex/errors/registry/pipelex-error-registry.yaml
@@ -71,8 +71,9 @@ codes:
steps:
actor: {kind: check_account, detail: "Add credit to the organization, or move it to a plan that includes more, then try again."}
other: {kind: contact_owner, detail: "Ask the account's owner to add credit to the organization."}
- params: {}
- meaning: "The organization's credit is spent. The platform refuses a run before queueing it, and a model call made once the credit has run out is refused as well."
+ params:
+ ledger: {type: enum, values: [inference, usage], optional: true, description: "The credit ledger whose balance refused the operation: the organization's inference credit or its usage credit."}
+ meaning: "The organization's credit is spent. The hosted platform keeps two credit ledgers, inference credit and usage credit, and refuses a run before queueing it while either is at zero or below, naming the ledger that refused it in `params.ledger`. A model call made once the credit has run out is refused as well, and names no ledger."
what_to_do: "Add credit to the organization, or move it to a plan that includes more, then start the run again."
- code: pipelex.billing.subscription_conflict
diff --git a/pipelex/errors/registry/pipelex_codes.py b/pipelex/errors/registry/pipelex_codes.py
index 542a51540..bbb45d2a5 100644
--- a/pipelex/errors/registry/pipelex_codes.py
+++ b/pipelex/errors/registry/pipelex_codes.py
@@ -117,10 +117,16 @@ class BillingCreditExhaustedParams(PipelexErrorParams):
"""The parameters of `pipelex.billing.credit_exhausted`.
The organization is out of credit.
+
+ Attributes:
+ ledger: The credit ledger whose balance refused the operation: the organization's inference credit or
+ its usage credit.
"""
code: ClassVar[PipelexErrorCode] = PipelexErrorCode.BILLING_CREDIT_EXHAUSTED
+ ledger: Literal["inference", "usage"] | None = None
+
class BillingSubscriptionConflictParams(PipelexErrorParams):
"""The parameters of `pipelex.billing.subscription_conflict`.