Give people understandable AI refusal messages

Purpose

Translate AI refusal classifications into customer language and recognizable next steps.

How It Works

The usage-message helper supplies customer sentences for allowance, concurrency, disabled-feature and service refusals. Allowance messages identify when AI can resume and point to support for more capacity. Brief concurrency limits ask the person to retry. Disabled features direct the person to support instead of suggesting renewal will turn them on. Operator configuration problems have no dedicated customer sentence. Describe With AI uses its console error adapter to display allowance wording, while HQ renders request reasons in words. Notice content shares the pause sentence with the customer helper. The product should verify each console refusal path because helper tests alone do not prove what every screen displays.

Relationships

Run AI requests with consistent attribution and accounting supplies the prerequisite behavior for this outcome.

Show evidence (sources, provenance, origins, pinned commits)

The Formal Contract

The narrative above explains; the sections below are authoritative — the rules, scenarios and tests this document binds.

Outcomes: Refusal wording explains waiting, retrying or contacting support.Customer wording excludes provider, model, money and internal control details.
Surfaces: consoleapi
Constraints: Exact customer wording remains subject to approval of the proposed plan.
Intent sources: services-platform:docs/proposals/llm-observability/11-decisions.md#11.1 Settled by inspection (reported)

Controls

26 controls apply, from the corpus control catalogue.

TC-AVL-001 TC-AVL-004 TC-AZ-001 TC-AZ-002 TC-AZ-003 TC-AZ-004 TC-DAT-001 TC-DAT-002 TC-DAT-003 TC-LOG-001 TC-LOG-004 TC-LOG-005 TC-MON-001 TC-PI-001 TC-PI-002 TC-PI-003 TC-PI-004 TC-PI-005 TC-PRV-001 TC-PRV-002 TC-TEN-001 TC-TEN-002 TC-TEN-003 TC-VEN-001 TC-VEN-002 TC-VEN-003

Business Rules

10 rules, 6 to be proved before approval. A rule's product intent is derived from its origin: 0 confirmed by a product decision, the rest inheriting this capability's proposed.

Id	Rule	Kind	Enforced at	Provenance
`01`must prove Proposed	Allowance-refusal wording explains that the period’s AI allowance is used and that AI resumes next month or sooner through support-provided capacity. proved by `ATS-PFM-LLM-001-18`, `ATS-PFM-LLM-017-11`, `ATS-PFM-LLM-018-01`, `TST-PFM-LLM-085`	policy	service	test services-platform:modules/llm/tests/unit/services/usage/usage-sentences.spec.ts#tells an organization that has used its allowance when it resumes
`02`must prove Proposed	Concurrency-refusal wording asks the person to wait a few seconds because too many organizational AI requests are running. proved by `ATS-PFM-LLM-018-01`, `TST-PFM-LLM-085`	policy	service	test services-platform:modules/llm/tests/unit/services/usage/usage-sentences.spec.ts#asks an organization with too many requests running to try again in a few seconds
`03`must prove Proposed	Disabled-feature wording says the organization’s AI feature is off and directs the person to Rhythm support for enablement. proved by `ATS-PFM-LLM-018-01`, `TST-PFM-LLM-085`	policy	service	test services-platform:modules/llm/tests/unit/services/usage/usage-sentences.spec.ts#tells an organization with a feature turned off to ask Rhythm support
`04`must prove Proposed	The helper gives provider unavailability and the declared circuit-open refusal the same temporary-service message, although a circuit breaker is not implemented. proved by `ATS-PFM-LLM-018-01`, `TST-PFM-LLM-085`	policy	service	test services-platform:modules/llm/tests/unit/services/usage/usage-sentences.spec.ts#says the same for an open circuit, because the organization cannot tell them apart
`05` Proposed	Operator faults such as missing configuration or depleted provider credit receive no specialized customer sentence.	policy	service	test services-platform:modules/llm/tests/unit/services/usage/usage-sentences.spec.ts#has no sentence for a fault that is an operator’s to read about
`06`must prove Proposed	Customer sentences use organization language and avoid internal money, model, provider and override terminology. origin: services-platform:docs/proposals/llm-observability/11-decisions.md#11.1 Settled by inspection (reported) proved by `ATS-PFM-LLM-018-02`, `TST-PFM-LLM-085`	policy	service	test services-platform:modules/llm/tests/unit/services/usage/usage-sentences.spec.ts#names a tenant, money, a model, a provider or an override in none of them
`07` Proposed	The pause email shares the customer pause sentence, substituting the organization’s name for the direct customer address. proved by `ATS-PFM-LLM-008-13`	policy	service	test services-platform:modules/llm/tests/unit/services/usage/usage-sentences.spec.ts#quote the same at-limit words, the notice naming the organization where the console says "your"
`08`must prove Proposed	Describe With AI displays allowance-refusal wording using a reset day supplied by the refusal or a next-month fallback. proved by `ATS-PFM-LLM-018-03`	policy	console	observed react-console:lib/api/generate-query.ts:allowanceMessage
`09` Proposed	Credit figures use thousands separators and date formatting uses day and month with a year where the message supplies one.	policy	service	observed services-platform:modules/llm/services/notices/threshold-notice.ts
`10` Proposed	HQ presents refusal reasons as readable labels or sentences instead of raw classifications.	policy	console	test react-console:lib/hq/ai-usage-format.test.ts#says a refusal code in words and never as the token

Scenarios

Id	Given	When	Then	Provenance
`01`	The organization has used its current allowance.	A person submits another AI request.	The proposed customer explanation gives the reset date and the option of support granting capacity.	documented services-platform:docs/milestones/plans/PLAT-M1-plan.md#3. How it works for the user

Planning

Implementation

Give people understandable AI refusal messages ​

Purpose ​

How It Works ​

Relationships ​