> ## 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/ko/packages/laravel-copilot-sdk/session-event.md)를 참조하세요.

### SessionTimeoutException

`session.idle`(응답 완료)을 기다리다 타임아웃되면 보관됩니다. 타임아웃은 `sendAndWait()`의 `timeout` 인수로 지정합니다. 생략하면 `copilot.timeout` 설정값(기본값 60초)이 사용됩니다.

### SessionErrorException

세션이 `SESSION_ERROR` 이벤트로 오류를 반환하면 보관됩니다. 메시지에는 런타임이 반환한 오류 내용이 포함됩니다.

## JsonRpcException

RPC 호출에 대해 CLI가 JSON-RPC 오류를 반환하면 즉시 던져집니다. JSON-RPC 오류 코드는 `code` 속성에서, 오류에 첨부된 데이터는 `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/ko/packages/laravel-copilot-sdk/fake.md)를 참조하세요.


## Related topics

- [SessionEvent](https://kawax.biz/ko/packages/laravel-copilot-sdk/session-event.md)
- [에러 처리](https://kawax.biz/ko/error-handling.md)
- [병행 처리](https://kawax.biz/ko/concurrency.md)
- [패키지의 외부 프로세스 실행과 Process::fake](https://kawax.biz/ko/advanced/package-processes.md)
- [패키지의 문자열 유효성 검사 규칙 등록](https://kawax.biz/ko/advanced/package-validation-extensions.md)


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