Error Handling
Octavus provides structured error handling across all transports. Errors are categorized by type and source, enabling you to build appropriate UI responses and monitoring.
Error Types
The onError callback receives an OctavusError with structured information:
typescript
Error Classification
Error Types
| Type | Description | Typical Response |
|---|---|---|
rate_limit_error | Too many requests | Show retry timer |
quota_exceeded_error | Usage quota exceeded | Show upgrade prompt |
authentication_error | Invalid API key | Check configuration |
permission_error | No access to resource | Check permissions |
validation_error | Invalid request | Fix request data |
provider_error | LLM provider issue | Retry or show error |
provider_overloaded | Provider at capacity | Retry with backoff |
provider_timeout | Provider timed out | Retry |
tool_error | Tool execution failed | Show tool error |
internal_error | Platform error | Show generic error |
Error Sources
| Source | Description |
|---|---|
platform | Octavus platform error |
provider | LLM provider error (OpenAI, Anthropic, etc.) |
tool | Tool execution error |
client | Client-side error (network, parsing) |
Type Guards
Use type guards to handle specific error types:
typescript
Provider Error Details
When errors come from LLM providers, additional details are available:
typescript
Building Error UI
tsx
Monitoring & Logging
Log errors for monitoring and debugging:
typescript
Error State
The hook exposes error state directly:
typescript
Rate Limit Handling
Rate limits include retry information:
typescript
Error Event Structure
For custom transports or direct event handling, errors follow this structure:
typescript
Tool Errors
Tool errors are handled differently—they appear inline on the tool call:
tsx
Tool errors don't trigger onError—they're captured on the tool call part itself.