---
id: WF-PFM-LLM-015
title: Explain a refused or failed request
trigger: 'Explain a refusal, failure or exhausted conversation budget.'
product_area: platform
module: llm
revision: 1
status: draft
design_intent: proposed
implementation_evidence: observed
inference: []
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
implements:
  - CAP-PFM-LLM-012
crosses:
  - SVC-PFM-LLM-llm
idempotency: Explanation performs read-only admission checks and cannot reserve credits.
concurrency: >-
  Stored refusal snapshots remain stable, while current figures can change across the independent reads that
  assemble an explanation.
hops:
  - 'n': 1
    actor_or_service: Rhythm HQ console (request detail)
    action: Load explanation within the request-detail panel for an explainable result.
    anchor: 'react-console:components/console/hq/ai-usage/request/explain-panel.tsx:ExplainPanel'
    seam: sync
    on_failure: Show an independent panel error.
    left_inconsistent: No mutation occurs.
    observer: Request explanation panel and API response.
    provenance: observed
    source: 'react-console:components/console/hq/ai-usage/ai-usage-request-detail.tsx:AiUsageRequestDetail'
  - 'n': 2
    actor_or_service: LLM usage API
    action: Authorize HQ usage read and enter the requested organization.
    anchor: 'services-platform:modules/llm/aws/api/llm-usage.routes.ts:explainHqTenantLlmUsageInvocation'
    seam: sync
    on_failure: Reject missing authority and return not-found for absent organization or foreign request.
    left_inconsistent: No explanation write occurs.
    observer: Request explanation panel and API response.
    provenance: observed
    source: 'services-platform:modules/llm/services/usage-reports/tenant-usage.ts:enterUsageTenant'
  - 'n': 3
    actor_or_service: Explanation service
    action: >-
      Use the retained refusal snapshot, resolve referenced grants and compare the same estimate against
      current read-only admission.
    anchor: 'services-platform:modules/llm/services/explain/explain-invocation.ts:explainInvocation'
    seam: sync
    on_failure: Propagate read failures without reserving capacity.
    left_inconsistent: No allowance movement or evidence read occurs.
    observer: Request explanation panel and API response.
    provenance: observed
    source: 'services-platform:modules/llm/services/persistence/allowance-periods.ts:wouldAuthorizeCredits'
  - 'n': 4
    actor_or_service: Explanation service
    action: Describe failed or limited outcomes through routing budgets and retained attempts with retry verdicts.
    anchor: 'services-platform:modules/llm/services/explain/explain-invocation.ts:verdictOf'
    seam: sync
    on_failure: Reject healthy completed work as having nothing to explain.
    left_inconsistent: No stored history is changed.
    observer: Request explanation panel and API response.
    provenance: observed
    source: 'services-platform:modules/llm/services/explain/explain-sentences.ts:loopLimitSentence'
branches:
  - Legacy refusals without a snapshot use retained estimates for the present admission check.
waits: []
evidence:
  - >-
    services-platform at ad3f6a6: modules/llm/aws/api/llm-usage.routes.ts;
    services/explain/explain-invocation.ts, explain-sentences.ts;
    services/persistence/allowance-periods.ts:wouldAuthorizeCredits, overrides.ts;
    services/usage-reports/tenant-usage.ts; docs/llm.md#Explaining a refusal.
  - >-
    react-console at baf6dae: components/console/hq/ai-usage/request/explain-panel.tsx,
    ai-usage-request-detail.tsx.
controls: [TC-AI-006, TC-AI-007, TC-AVL-001, TC-AVL-004, TC-AVL-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-IAM-001, TC-IAM-002, TC-IAM-003, TC-IAM-004, TC-IAM-005, TC-LOG-001, TC-LOG-002, TC-LOG-003, 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]
---

# Explain a refused or failed request

## What It Does

Support reads retained decision-time figures alongside present allowance state, or inspects provider attempts and budget outcomes.

## The Flow

```mermaid
flowchart TD
  H1["Load explanation within the request-detail panel for an explainable result."]
  H2["Authorize HQ usage read and enter the requested organization."]
  H1 --> H2
  H3["Use the retained refusal snapshot, resolve referenced grants and compare the same estimate against current read-only admission."]
  H2 --> H3
  H4["Describe failed or limited outcomes through routing budgets and retained attempts with retry verdicts."]
  H3 --> H4
```

The read enters the selected organization, resolves stored snapshots and grants, and tests current admission without holding credits.

## When Something Fails

Missing references remain visible as unavailable rather than being erased. Panel failures have no accounting or content-reading side effect.

## Open Design Questions

The open meaning of exhaustion still affects customer wording; explanation does not choose that policy.