Saltar al contenido principal

Excepciones y manejo de errores

Todas las excepciones que lanza el SDK están en el namespace Revolution\Copilot\Exceptions. Aparecen de dos formas: algunas se guardan en el resultado de la sesión y se lanzan al llamar a throw(), y otras se lanzan de inmediato, por ejemplo en las llamadas RPC.

Errores y timeouts de sesión

Con sendAndWait() y Copilot::run(), un error o timeout de sesión no se lanza en el momento. En su lugar, la excepción se guarda en el SessionEvent devuelto. Igual que con Http y Process de Laravel, llamar a throw() lanza la excepción guardada. Si no hay error, throw() no hace nada, así que puedes seguir encadenando métodos.
Para comprobar el éxito sin lanzar excepciones, usa failed() y successful(). Consulta SessionEvent para más detalles.

SessionTimeoutException

Se guarda cuando la espera de session.idle (la finalización de la respuesta) agota el tiempo. Establece el tiempo límite con el argumento timeout de sendAndWait(). Si lo omites, se usa el valor de configuración copilot.timeout (60 segundos por defecto).

SessionErrorException

Se guarda cuando la sesión devuelve un error mediante un evento SESSION_ERROR. El mensaje contiene el error devuelto por el runtime.

JsonRpcException

Se lanza de inmediato cuando la CLI devuelve un error JSON-RPC para una llamada RPC. Lee el código de error JSON-RPC en la propiedad code y los datos adjuntos al error en la propiedad data.

SessionFsSqliteTransactionFailure

Usa esta excepción cuando implementes un proveedor SQLite de SessionFs. No la capturas: la lanzas desde transaction() del proveedor para indicar al runtime cómo debe clasificarse el fallo. Establece la clasificación con errorClass:
  • Fatal (predeterminado): un fallo irrecuperable
  • BusyOrLocked: úsalo solo cuando SQLite devolvió BUSY/LOCKED antes del commit y la transacción se revirtió
  • PostCommitAmbiguous: no se puede determinar el resultado después del commit
Cualquier otra excepción lanzada desde transaction() se informa como fatal.

StrayRequestException

La lanza el fake de pruebas cuando envías una solicitud sin un fake coincidente registrado. Si aparece de forma inesperada, olvidaste registrar un fake para esa solicitud. Consulta Pruebas para saber cómo usar los fakes.
Última modificación el 15 de noviembre de 2026