> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# 异常与错误处理

> 了解 Laravel Copilot SDK 会抛出哪些异常及其发生条件、如何通过 throw() 捕获，以及 JSON-RPC 错误和 SessionFs SQLite 提供者中的处理方式。

## 异常与错误处理

SDK 抛出的所有异常都位于 `Revolution\Copilot\Exceptions` 命名空间中。异常的出现方式有两种：一种保存在会话的执行结果中，调用 `throw()` 时才抛出；另一种在 RPC 调用等场合当场抛出。

## 会话错误与超时

在 `sendAndWait()` 和 `Copilot::run()` 中，会话错误或超时不会当场抛出，而是将异常保存在返回的 `SessionEvent` 中。与 Laravel 的 Http 和 Process 一样，调用 `throw()` 会抛出保存的异常。没有错误时 `throw()` 不做任何事，因此可以继续链式调用方法。

```php theme={null}
use Revolution\Copilot\Exceptions\SessionErrorException;
use Revolution\Copilot\Exceptions\SessionTimeoutException;
use Revolution\Copilot\Facades\Copilot;

try {
    $content = Copilot::run('Calculate 1 + 1')->throw()->content();
} catch (SessionTimeoutException $e) {
    // 处理超时
} catch (SessionErrorException $e) {
    // 处理会话错误
}
```

如需在不抛出异常的情况下检查是否成功，请使用 `failed()` 和 `successful()`。详情请参阅 [SessionEvent](https://kawax.biz/zh-CN/packages/laravel-copilot-sdk/session-event.md)。

### SessionTimeoutException

等待 `session.idle`（响应完成）超时时保存。超时时间通过 `sendAndWait()` 的 `timeout` 参数指定。省略时使用配置值 `copilot.timeout`（默认 60 秒）。

### SessionErrorException

会话通过 `SESSION_ERROR` 事件返回错误时保存。消息中包含运行时返回的错误内容。

## JsonRpcException

当 CLI 针对 RPC 调用返回 JSON-RPC 错误时立即抛出。从 `code` 属性读取 JSON-RPC 错误码，从 `data` 属性读取附加到错误的数据。

```php theme={null}
use Revolution\Copilot\Exceptions\JsonRpcException;
use Revolution\Copilot\Facades\Copilot;

try {
    Copilot::client()->rpc()->ping();
} catch (JsonRpcException $e) {
    $e->code; // JSON-RPC 错误码
    $e->data; // 附加到错误的数据
}
```

## SessionFsSqliteTransactionFailure

这是实现 SessionFs 的 SQLite 提供者时使用的异常。它不是用来捕获的，而是从提供者的 `transaction()` 中抛出，以告诉运行时应如何对失败进行分类。分类通过 `errorClass` 指定：

* `Fatal`（默认）：无法恢复的失败
* `BusyOrLocked`：仅在 SQLite 于提交前返回 BUSY/LOCKED 且事务已回滚时使用
* `PostCommitAmbiguous`：无法确定提交后的结果

从 `transaction()` 抛出的其他任何异常都会作为 `fatal` 报告。

```php theme={null}
use Revolution\Copilot\Enums\SessionFSSqliteTransactionErrorClass;
use Revolution\Copilot\Exceptions\SessionFsSqliteTransactionFailure;

throw new SessionFsSqliteTransactionFailure(
    'database is locked',
    SessionFSSqliteTransactionErrorClass::BusyOrLocked,
);
```

## StrayRequestException

测试用 fake 在你发送没有注册匹配 fake 的请求时抛出。如果意外出现，说明你忘记为该请求注册 fake。fake 的用法请参阅[测试](https://kawax.biz/zh-CN/packages/laravel-copilot-sdk/fake.md)。


## Related topics

- [SessionEvent](https://kawax.biz/zh-CN/packages/laravel-copilot-sdk/session-event.md)
- [错误处理](https://kawax.biz/zh-CN/error-handling.md)
- [Laravel Pennant](https://kawax.biz/zh-CN/pennant.md)
- [Laravel Pulse](https://kawax.biz/zh-CN/pulse.md)
- [包中的外部进程执行与 Process::fake](https://kawax.biz/zh-CN/advanced/package-processes.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.