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:
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:
Provider Error Details
When errors come from LLM providers, additional details are available:
Retrying After Errors
Use retry() to re-execute the last trigger from the same starting point. Messages are rolled back, the user message is re-added (if any), and the agent re-executes. Files are reused without re-uploading.
retry() also works after stopping (cancellation) or when the result is unsatisfactory — not just errors.
Building Error UI
Monitoring & Logging
Log errors for monitoring and debugging:
Error State
The hook exposes error state directly:
Rate Limit Handling
Rate limits include retry information:
Error Event Structure
For custom transports or direct event handling, errors follow this structure:
Tool Errors
Tool errors are handled differently—they appear inline on the tool call:
Tool errors don't trigger onError—they're captured on the tool call part itself.