> ## 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-TW/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-TW/packages/laravel-copilot-sdk/fake.md)。


## Related topics

- [SessionEvent](https://kawax.biz/zh-TW/packages/laravel-copilot-sdk/session-event.md)
- [錯誤處理](https://kawax.biz/zh-TW/error-handling.md)
- [Laravel Pennant](https://kawax.biz/zh-TW/pennant.md)
- [用 Inertia.js 建構 SPA](https://kawax.biz/zh-TW/blog/inertia-introduction.md)
- [套件的外部程序執行與 Process::fake](https://kawax.biz/zh-TW/advanced/package-processes.md)


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