# AiErrorView
## Description
BitAiErrorView shows an error the user can act on: what went wrong, a retry button when the error says retrying could help and a handler is there to do it, how long to wait before retrying when the provider says so, and the technical detail behind a disclosure rather than in the reader's face. It draws the error as an Error BitMessage, which is announced as an alert, and has a compact form for a failure shown inside another card.
## Parameters
| Name | Type | Default Value | Description |
| :--- | :--- | :------------ | :---------- |
| Classes | `BitAiErrorViewClassStyles?` | null | Custom CSS classes for different parts of the error view. |
| Compact | `bool` | false | Renders the error for a place inside another card that already says what failed (a tool call, a tool result): it is titled by its own message instead of the generic heading, and the message is not repeated under it. |
| Error | `BitAiError` | | The failure to show (required). Its Message is the text, IsRetryable decides whether the retry is offered, RetryAfter adds how long to wait, and Detail goes behind the disclosure. |
| OnRetry | `EventCallback` | | Raised when the user asks to retry - typically BitAiChatSession.RetryAsync. The retry button is hidden while it is unset and while the error says retrying would not help (IsRetryable is false), and does nothing while the view is disabled. |
| Styles | `BitAiErrorViewClassStyles?` | null | Custom CSS styles for different parts of the error view. |
| AriaLabel | `string?` | null | Gets or sets the accessible label for the component, used by assistive technologies. |
| Class | `string?` | null | Gets or sets the CSS class name(s) to apply to the rendered element. |
| Dir | `BitDir?` | null | Gets or sets the text directionality for the component's content. |
| Disabled | `bool` | false | Gets or sets a value indicating whether the component is disabled and cannot respond to user interaction. |
| ForceAnimation | `bool` | false | Gets or sets a value indicating whether the component's animations play at their full duration even when reduced motion is requested. |
| HtmlAttributes | `Dictionary<string, object>` | new Dictionary<string, object>() | Captures additional HTML attributes to be applied to the rendered element, in addition to the component's parameters. An attribute written on the component wins over an entry of the same name. |
| Id | `string?` | null | Gets or sets the unique identifier for the component's root element. |
| Style | `string?` | null | Gets or sets the CSS style string to apply to the rendered element. |
| TabIndex | `string?` | null | Gets or sets the tab order index for the component when navigating with the keyboard. |
| Visibility | `BitVisibility` | BitVisibility.Visible | Gets or sets the visibility state (visible, hidden, or collapsed) of the component. |
## Public Members
| Name | Type | Default Value | Description |
| :--- | :--- | :------------ | :---------- |
| UniqueId | `Guid` | Guid.NewGuid() | Gets the readonly unique identifier for the component's root element, assigned when the component instance is constructed. |
| RootElement | `ElementReference` | | Gets the reference to the root HTML element associated with this component. |
## Enums
### BitAiErrorKind Enum
| Name | Value | Description |
| :--- | :--- | :---------- |
| Unknown | 0 | Unclassified failure. |
| Network | 1 | The network or the transport failed. |
| Authentication | 2 | Credentials are missing, invalid or expired. |
| Authorization | 3 | The caller is authenticated but not permitted. |
| RateLimit | 4 | The provider is rate limiting the caller. |
| ContextLength | 5 | The request exceeded the context window of the model. |
| ContentFilter | 6 | A safety system of the provider refused the request. |
| InvalidRequest | 7 | The provider rejected the request as malformed. |
| Provider | 8 | The provider failed internally. |
| Tool | 9 | A tool threw or returned a failure while running. |
| Timeout | 10 | The request timed out. |
| Cancelled | 11 | The caller cancelled the request. |
### BitVisibility Enum
| Name | Value | Description |
| :--- | :--- | :---------- |
| Visible | 0 | The content of the component is visible. |
| Hidden | 1 | The content of the component is hidden, but the space it takes on the page remains (visibility:hidden). |
| Collapsed | 2 | The component is hidden (display:none). |
### BitDir Enum
| Name | Value | Description |
| :--- | :--- | :---------- |
| Ltr | 0 | Ltr (left to right) is to be used for languages that are written from the left to the right (like English). |
| Rtl | 1 | Rtl (right to left) is to be used for languages that are written from the right to the left (like Arabic). |
| Auto | 2 | Auto lets the user agent decide. It uses a basic algorithm as it parses the characters inside the element until it finds a character with a strong directionality, then applies that directionality to the whole element. |
## Sub Classes
### BitAiErrorViewClassStyles Properties
| Name | Type | Default Value | Description |
| :--- | :--- | :------------ | :---------- |
| Root | `string?` | null | Custom CSS classes/styles for the root element of the BitAiErrorView. |
| Message | `BitMessageClassStyles?` | null | Custom CSS classes/styles for the BitMessage the BitAiErrorView draws the error with: its surface, icon, title and content. |
| Text | `string?` | null | Custom CSS classes/styles for the text of the error of the BitAiErrorView (not rendered when Compact, whose title is that text). |
| RetryAfter | `string?` | null | Custom CSS classes/styles for the line saying how long to wait before retrying, of the BitAiErrorView. |
| Detail | `string?` | null | Custom CSS classes/styles for the technical detail of the BitAiErrorView. |
| Actions | `string?` | null | Custom CSS classes/styles for the row of the action buttons of the BitAiErrorView, rendered when there is a button to show. |
| RetryButton | `BitButtonClassStyles?` | null | Custom CSS classes/styles for the retry button of the BitAiErrorView. |
| DetailButton | `BitButtonClassStyles?` | null | Custom CSS classes/styles for the button disclosing the technical detail of the BitAiErrorView. |
### BitAiError Properties
A transport- and provider-independent description of a failure, fit for display and for driving the retry (a sealed record). Transports translate their own exceptions into it, so no component branches on the exception type of a provider's SDK.
| Name | Type | Default Value | Description |
| :--- | :--- | :------------ | :---------- |
| BitAiError(message) | `constructor` | | Creates an error with the message to show to the user. |
| Message | `string` | | A human-readable message, safe to show to the end user. |
| Code | `string?` | null | A stable machine-readable code, for example rate_limit. |
| Kind | `BitAiErrorKind` | BitAiErrorKind.Unknown | The kind of failure, which the app can drive its own recovery from. The view draws every kind the same way; an agent run ended with an error of the Cancelled kind (BitAiAgentRun.SetError) ends as cancelled rather than failed. |
| IsRetryable | `bool` | false | Whether retrying the same request could plausibly succeed. The view offers the retry only when it is true. |
| RetryAfter | `TimeSpan?` | null | How long to wait before retrying, when the provider says so. The view shows it under the message from when it is handed the error until the wait is over, then takes the line away (it is not counted down: the message is an alert, which would announce every second). |
| Detail | `string?` | null | Additional technical detail, shown behind a disclosure rather than inline - to the user, so never a stack trace or anything else they must not read. |
| Exception | `Exception?` | null | The originating exception, if any. Never serialized and never shown. |
| FromException(exception) | `BitAiError` | | Translates an exception: an OperationCanceledException into a Cancelled error (code cancelled, not retryable), a TimeoutException into a retryable Timeout one (code timeout), anything else into a retryable Unknown one carrying the exception's message - which is shown, so a transport whose exceptions say what users must not read translates them itself. The stack trace is never put in the Detail, which is shown too; the exception stays on Exception, for the app's logs. |
## CSS Variables
Public CSS custom properties read off the component's root. Set one on `:root` to restyle every instance, on any ancestor to restyle the ones inside it, or on the `Style` of one instance to restyle it and every instance nested inside it, which inherits the value too - a parameter changes one alone, as does the real CSS property on its `Style` / `Styles` when that property does not inherit (`opacity`); an inherited one (`color`, `font-family`) reaches the nested instances that do not set it themselves.
| Name | Default Value | Description |
| :--- | :------------ | :---------- |
| `--bit-AiErrorView-detail-color` | var(--bit-clr-fg-sec) | Color of the technical detail. |
| `--bit-AiErrorView-detail-max-height` | spacing(24) | Height past which the technical detail scrolls. |
## Examples
\n**Basic**:
```razor
Ask
Start over
@if (retrySession.LastError is { } lastError)
{
Monthly report
```
```csharp
private readonly BitAiError detailError = new("The report service did not answer.")
{
Code = "upstream_unavailable",
Kind = BitAiErrorKind.Provider,
IsRetryable = true,
RetryAfter = TimeSpan.FromSeconds(30),
Detail = """
HTTP 503 Service Unavailable
x-request-id: 7f3c2a91-4e0b-4f6e-9b1d-2c8a5e0d3b44
retry-after: 30
{
"error": {
"type": "overloaded",
"message": "The report service is overloaded. Try again later."
}
}
""",
};
```
\n**From an exception**:
```razor
```
```csharp
private readonly BitAiErrorViewParams[] errorViewParams =
[
new() { Styles = new() { RetryButton = new() { Root = "border-radius: 1rem" }, Detail = "font-size: 0.875rem" } },
];
private int detailRetries;
private readonly BitAiError timeoutError = BitAiError.FromException(new TimeoutException());
private readonly BitAiError detailError = new("The report service did not answer.")
{
Code = "upstream_unavailable",
Kind = BitAiErrorKind.Provider,
IsRetryable = true,
RetryAfter = TimeSpan.FromSeconds(30),
Detail = """
HTTP 503 Service Unavailable
x-request-id: 7f3c2a91-4e0b-4f6e-9b1d-2c8a5e0d3b44
retry-after: 30
{
"error": {
"type": "overloaded",
"message": "The report service is overloaded. Try again later."
}
}
""",
};
```
\n**Style & Class**:
```razor
@answer.GetText()
}
```
```csharp
private BitAiRenderScheduler sessionRenders = default!;
private BitAiChatSession retrySession = default!;
protected override void OnInitialized()
{
// At most one render of the page per frame interval, however often the session changes.
sessionRenders = new BitAiRenderScheduler(() => InvokeAsync(StateHasChanged));
retrySession = CreateRetrySession();
}
// A scripted model that is rate limited on its first try and answers on the second.
private BitAiChatSession CreateRetrySession()
{
var session = new BitAiChatSession(AiDemoInteractiveTransports.FailsThenRecovers());
session.StateChanged += sessionRenders.Request;
return session;
}
private Task AskAsync() => retrySession.SubmitAsync("Summarise the release notes");
private Task RetryAsync() => retrySession.RetryAsync();
private async Task StartOverAsync()
{
await retrySession.DisposeAsync();
retrySession = CreateRetrySession();
}
public async ValueTask DisposeAsync()
{
await retrySession.DisposeAsync();
await sessionRenders.DisposeAsync();
}
```
\n**Detail**:
```razor
Retried @detailRetries times.
```
```csharp
private int detailRetries;
private readonly BitAiError detailError = new("The report service did not answer.")
{
Code = "upstream_unavailable",
Kind = BitAiErrorKind.Provider,
IsRetryable = true,
RetryAfter = TimeSpan.FromSeconds(30),
Detail = """
HTTP 503 Service Unavailable
x-request-id: 7f3c2a91-4e0b-4f6e-9b1d-2c8a5e0d3b44
retry-after: 30
{
"error": {
"type": "overloaded",
"message": "The report service is overloaded. Try again later."
}
}
""",
};
```
\n**Compact**:
```razor
Retried @exceptionRetries times.
```
```csharp
private int exceptionRetries;
private readonly BitAiError cancelledError = BitAiError.FromException(new OperationCanceledException());
private readonly BitAiError timeoutError = BitAiError.FromException(new TimeoutException());
private readonly BitAiError unknownError = FromThrownException();
private static BitAiError FromThrownException()
{
try
{
throw new InvalidOperationException("The search index is out of date.");
}
catch (Exception exception)
{
return BitAiError.FromException(exception);
}
}
```
\n**Disabled**:
```razor
Retried @rtlRetries times.
```
```csharp
private int rtlRetries;
private readonly BitAiUiOptions persianOptions = BitAiUiOptions.Default with { Strings = new PersianAiStrings() };
private readonly BitAiError rtlError = new("سرویس گزارش پاسخ نداد.")
{
IsRetryable = true,
RetryAfter = TimeSpan.FromSeconds(30),
Detail = "HTTP 503 Service Unavailable",
};
// The words of the view, in Persian.
private sealed class PersianAiStrings : BitAiStrings
{
public override string SomethingWentWrong => "مشکلی پیش آمد";
public override string Retry => "تلاش دوباره";
public override string ShowDetails => "نمایش جزئیات";
public override string HideDetails => "پنهان کردن جزئیات";
public override string RetryIn(TimeSpan wait) => $"{wait.TotalSeconds:F0} ثانیهی دیگر دوباره تلاش کنید.";
}
```