Outcomes and errors

Public documentation preview — incomplete. The SDK and optional AI SDK peers remain private and unpublished. This summary is not the complete failure-code or release-compatibility matrix.

router.call() and router.execute() return an ExecutionResult. It has an operation identity, stage, status, code, retryable and sideEffectState; some variants contain a tool ID, question, approval proposal, validation issues or result. Inspect status before reading a payload or retrying.

Status	Meaning	Dispatch/effect guidance
`executed`	Validated, authorized call completed	`sideEffectState: 'completed'`; inspect its result only in trusted host code
`no_match`	No matching action	`not_started`; ask for a better request or explicitly scoped sources
`needs_input`	Clarification or required facts are missing	`not_started`; never invent missing customer facts
`denied`	Policy refused the exact action	`not_started`; do not silently retry or switch targets
`pending_approval`	Host approval is required	`not_started`; no dispatch; host must handle approval and revalidation explicitly
`invalid_arguments`	Proposed inputs failed validation	`not_started`; use safe issue paths/codes, not the rejected input
`failed`	Typed operational failure	Check `code` and `sideEffectState`; tool errors may still be `completed`
`cancelled` / `timed_out`	Work did not complete in the calling window	`not_started` or `unknown`; unknown means effects are not proven absent

SideEffectState is exactly 'not_started' | 'unknown' | 'completed'. Unknown does not mean rolled back. After uncertain dispatch, use your own idempotency/reconciliation workflow before deciding whether another call is safe. A retryable flag does not override host approval or this uncertainty. Malformed configuration/options can throw RouterConfigError (invalid_config, safe path). Operational selection/discovery methods can throw RouterOperationError with a typed stage/code/effect state instead of returning an ExecutionResult; handle both cases without leaking credentials or prompt content. Examples of operational codes include stale_tool, catalogue_stale, unsupported_schema, model_access_denied, provider_error, capacity_exceeded and cleanup_failed. This starter page is a summary, not the exhaustive union/code matrix required before full documentation acceptance. Follow the first governed call, bounded execution and trust boundaries for context.

Get started

Integrate

Guides

Reference

Outcomes and errors

Outcomes and errors

​Outcomes and errors

Outcomes and errors