Errors and events
Find capability-owned error and event contracts without confusing SDK results, transport messages and CLI diagnostics.
Look up the owning error contract
There is no universal Framework error envelope. Narrow the result or catch the error defined by the capability you called; do not branch on message text.
For handling details, see Service errors, model retries, Tool recovery and Worker recovery.
Keep event formats separate
To configure provider logs and correlate errors, see provider diagnostics. Keep raw exception messages, stacks and response bodies out of customer responses.
For durable vocabulary and storage, use Timeline and usage records. For browser delivery, use Agent streaming and recovery. Not every capability emits every event, and seeing an event does not establish a durable commit across stores.
Cancellation is not rollback
A cancelled request or disconnected stream does not prove that remote work stopped. A retryable failure is not permission to repeat a side effect. Reconcile uncertain writes and use application idempotency before retrying. Cancellation and timeouts cannot undo committed effects or guarantee that a provider made no charge.
CLI diagnostics are a separate interface
- Commands and structured output owns one-shot status, diagnostics, effects, check results and exit codes. MCP search/invocation use their own schemas.
- CI and troubleshooting owns investigation and redacted handoff evidence. Never expose arbitrary exceptions, provider bodies or script logs as safe user messages.