Exceptions¶
All of them inherit from SandboxException, except those that say something
about your environment rather than the sandbox (AuthenticationException and
its subclass GitAuthException, QuotaExceededException,
CapacityException), AgentCoreException (the AgentCore deploy) and
UnimplementedError (with its subclass
LifecycleUnsupportedException), which is a NotImplementedError.
RayitoCompatWarning is a UserWarning, not an exception: it warns about an
E2B option that Rayito ignores.
What to do about each one: Errors.
exceptions
¶
Jerarquía de excepciones del SDK (misma forma que la de E2B).
SandboxException es la raíz de todo lo que le ocurre a un sandbox concreto.
AuthenticationException, QuotaExceededException y CapacityException
quedan fuera de la jerarquía, como en E2B, porque describen la cuenta o el
caller, no el estado de un sandbox.
SandboxException(message: str, *, status_code: int | None = None, grpc_code: grpc.StatusCode | None = None, aws_code: str | None = None, code: str | None = None)
¶
Bases: Exception
Error atribuible a un sandbox.
status_code es el HTTP del plano de control, grpc_code el status del
agente y aws_code el nombre de la excepción de botocore; los tres son
opcionales según el origen. code es un código propio de Rayito de una
lista cerrada (agent_vm_lost: el MicroVM de un despliegue de agente
desapareció), None si el error no lo lleva.
TimeoutException(message: str, *, status_code: int | None = None, grpc_code: grpc.StatusCode | None = None, aws_code: str | None = None, code: str | None = None)
¶
Bases: SandboxException
Venció un plazo: el timeout de un comando o de run_code, el de una
llamada (DEADLINE_EXCEEDED) o el plazo del propio sandbox
(sandbox_timeout de rayd).
InvalidArgumentException(message: str, *, status_code: int | None = None, grpc_code: grpc.StatusCode | None = None, aws_code: str | None = None, code: str | None = None)
¶
Bases: SandboxException
Un argumento inválido, detectado por el SDK antes de llamar a nadie,
por el agente (INVALID_ARGUMENT, FAILED_PRECONDITION) o por la API de
AWS (ValidationException). El mensaje nombra el argumento.
NotFoundException(message: str, *, status_code: int | None = None, grpc_code: grpc.StatusCode | None = None, aws_code: str | None = None, code: str | None = None)
¶
Bases: SandboxException
Lo pedido no existe: un proceso, un contexto de código o un
checkpoint (NOT_FOUND, OUT_OF_RANGE del agente).
FileNotFoundException(message: str, *, status_code: int | None = None, grpc_code: grpc.StatusCode | None = None, aws_code: str | None = None, code: str | None = None)
¶
SandboxNotFoundException(message: str, *, status_code: int | None = None, grpc_code: grpc.StatusCode | None = None, aws_code: str | None = None, code: str | None = None)
¶
Bases: NotFoundException
El sandbox no existe o ya terminó (ResourceNotFoundException del
plano de control, o un MicroVM terminado al reconectar).
SandboxNotReadyException(message: str, *, state: str | None = None, state_reason: str | None = None, status_code: int | None = None, grpc_code: grpc.StatusCode | None = None, aws_code: str | None = None)
¶
Bases: SandboxException
El agente no respondió a Health dentro de ready_timeout.
state y state_reason vienen de la única llamada a get-microvm que se
hace tras el timeout; si el MicroVM murió en /run, state_reason lo dice.
SandboxStateException(message: str, *, status_code: int | None = None, grpc_code: grpc.StatusCode | None = None, aws_code: str | None = None, code: str | None = None)
¶
Bases: SandboxException
El sandbox no está en un estado que admita la operación: se está
suspendiendo, reanudando o terminando (puerta de fase de rayd, o
ConflictException del plano de control). Suele bastar reintentar.
SandboxLifetimeException(message: str, *, status_code: int | None = None, grpc_code: grpc.StatusCode | None = None, aws_code: str | None = None, code: str | None = None)
¶
Bases: SandboxException
timeout o max_lifetime por encima del tope de la plataforma
(28 800 s, 8 h contando running y suspendido); el SDK la lanza antes de
llamar a AWS.
PoolClosedException(message: str, *, status_code: int | None = None, grpc_code: grpc.StatusCode | None = None, aws_code: str | None = None, code: str | None = None)
¶
CommandExitException(message: str, *, exit_code: int, stdout: str = '', stderr: str = '', error: str | None = None, grpc_code: grpc.StatusCode | None = None, truncated: bool = False)
¶
Bases: SandboxException
Un comando terminó con exit code distinto de cero. truncated es
True cuando stdout o stderr superaron max_output_bytes y sólo
conservan su final.
PersistenceException(message: str, *, code: str, grpc_code: grpc.StatusCode | None = None)
¶
Bases: SandboxException
Checkpoint/Restore fallaron con un code cerrado: permission_denied
(sin execution role, AccessDenied o credenciales rechazadas), internal
(red, S3 5xx, tar/gzip, checksum, disco lleno), failed_precondition
(otra operación en curso o región desconocida), unimplemented (imagen
con un rayd anterior a Checkpoint), interrupted (stream cortado a
mitad por un suspend o el proxy; no se reanuda) o resource_exhausted.
DiskFullException(message: str, *, status_code: int | None = None, grpc_code: grpc.StatusCode | None = None, aws_code: str | None = None, code: str | None = None)
¶
Bases: SandboxException
Write rechazado por espacio: rayd exige 256 MiB libres antes de
cada fichero (disk_reserve) y mapea ENOSPC durante la escritura
(disk_full); grpc_code es RESOURCE_EXHAUSTED en ambos casos.
TransferException(message: str, *, code: str, reason: str, grpc_code: grpc.StatusCode | None = None)
¶
Bases: SandboxException
Una transferencia por S3 (download_url, lectura grande) terminó
FAILED o CANCELLED con un code sin excepción propia
(failed_precondition, unavailable, cancelled, internal o uno
desconocido). reason es el token de rayd (checksum_mismatch,
file_shrank, s3_unavailable...); el mensaje empieza por "<reason>: "
y nunca contiene una URL, un bucket, una clave ni una ruta.
FileUploadException(message: str, *, code: str, reason: str, grpc_code: grpc.StatusCode | None = None)
¶
Bases: TransferException
La importación de un UploadTicket o de una escritura grande terminó
FAILED o CANCELLED con un code sin excepción propia (el nombre de
E2B para una subida fallida).
RateLimitException(message: str, *, retry_after: float | None = None, status_code: int | None = None, grpc_code: grpc.StatusCode | None = None, aws_code: str | None = None)
¶
Bases: SandboxException
Límite de tasa o de recursos: RESOURCE_EXHAUSTED del agente
(procesos, PTYs, contextos o transferencias simultáneas) o
ThrottlingException de AWS. retry_after son los segundos que AWS
sugiere esperar, si los dio.
AuthenticationException(message: str, *, proxy_rejected: bool = False, grpc_code: grpc.StatusCode | None = None, aws_code: str | None = None)
¶
Bases: Exception
Credenciales o token rechazados por AWS, por el proxy o por el agente.
proxy_rejected es True sólo cuando el 403 vino del proxy de AWS (JWE
ausente, expirado o sin el puerto): el SDK reacuña y reintenta una vez.
GitAuthException(message: str, *, proxy_rejected: bool = False, grpc_code: grpc.StatusCode | None = None, aws_code: str | None = None)
¶
Bases: AuthenticationException
Un comando git del módulo sandbox.git falló por credenciales: el
remoto pidió usuario y contraseña (GIT_TERMINAL_PROMPT=0 no deja
preguntar) o los rechazó. El mensaje nombra la acción de git y nunca
contiene la URL ni las credenciales.
GitUpstreamException(message: str, *, status_code: int | None = None, grpc_code: grpc.StatusCode | None = None, aws_code: str | None = None, code: str | None = None)
¶
Bases: SandboxException
git push/git pull sin rama remota configurada: el mensaje explica
cómo fijarla (set_upstream=True o remote/branch explícitos).
SecretException(message: str, *, status_code: int | None = None, grpc_code: grpc.StatusCode | None = None, aws_code: str | None = None, code: str | None = None)
¶
Bases: SandboxException
Error de un secreto de Secrets Manager (SecretStore, SecretCache,
secrets=, y el Secret/AsyncSecret del shim de E2B). El mensaje
nunca contiene el valor ni el nombre del secreto (los nombres son
selectores confidenciales, como en E2B); con secrets= nombra la clave
de la variable de entorno. aws_code es el Code de AWS, si lo hubo.
Divergencia con E2B: allí SecretException hereda de Exception; aquí
de SandboxException, para que un except SandboxException de Rayito
también la atrape.
SecretNotFoundException(message: str, *, status_code: int | None = None, grpc_code: grpc.StatusCode | None = None, aws_code: str | None = None, code: str | None = None)
¶
Bases: SecretException, NotFoundException
El secreto no existe o está programado para borrarse. También es la
NotFoundException nativa. Nunca se guarda en SecretCache.
SandboxIndexException(message: str, *, status_code: int | None = None, grpc_code: grpc.StatusCode | None = None, aws_code: str | None = None, code: str | None = None)
¶
Bases: SandboxException
Error del índice opcional de metadatos (DynamoDbIndex): la
tabla no existe, faltan permisos IAM o BatchGetItem dejó claves sin
procesar tras los reintentos. Un listado con índice nunca devuelve una
lista incompleta en silencio. El mensaje nunca repite el de AWS;
aws_code es el Code de DynamoDB, si lo hubo.
IndexWriteException(message: str, *, status_code: int | None = None, grpc_code: grpc.StatusCode | None = None, aws_code: str | None = None, code: str | None = None)
¶
Bases: SandboxIndexException
create(index=...) no pudo escribir la fila del sandbox (PutItem).
Con on_write_failure='terminate' (por defecto) el MicroVM ya se
terminó, salvo keep_on_failure=True.
QuotaExceededException(message: str, *, quota_code: str | None = None)
¶
Bases: Exception
Cuota de la cuenta agotada (ServiceQuotaExceededException): no
describe un sandbox, por eso no es SandboxException. quota_code es el
código de Service Quotas, si AWS lo dio.
CapacityException(message: str = '', *, code: str | None = None)
¶
Bases: Exception
AWS no tiene capacidad momentánea para el MicroVM
(InsufficientCapacityException); se reintenta con backoff. No es
SandboxException. code es agent_capacity cuando es una flota de
agentes la que no tiene cupo (todas las sesiones en uso y max_vms
alcanzado hasta agotar el plazo de la cola), None en el resto.
RayitoCompatWarning
¶
Bases: UserWarning
Aviso de compatibilidad: un kwarg de E2B que Rayito ignora
(api_key, domain, debug, api_url, sandbox_url,
validate_api_key, api_headers, secure=False), o la primera vez que
un proceso usa secrets= (fase 1: el valor inyectado es visible para el
código del sandbox). El aviso nombra el kwarg, nunca su valor.
UnimplementedError(feature: str, reason: str, doc: str | None = None)
¶
Bases: NotImplementedError
Una feature que este sandbox no puede ofrecer: falta configuración
(upload_url sin transfer=S3Staging(...)), la imagen corre un rayd
anterior o AWS no tiene la primitiva.
No es SandboxException a propósito, como NotImplementedError: un
except SandboxException no debe tragarse una feature ausente.
feature y reason describen qué falta y por qué; doc es la página
que lo explica (el shim de E2B pasa la de compatibilidad). El mensaje
nunca contiene datos del usuario.
LifecycleUnsupportedException(feature: str, reason: str, doc: str | None = None)
¶
Bases: UnimplementedError
El agente del sandbox es anterior a 0.3.0 y no impone el timeout del
servidor (Health sin lifecycle, o UNIMPLEMENTED en SetTimeout):
hace falta publicar una imagen 0.3.0 o posterior o crear el sandbox sin max_lifetime
ni on_timeout. Subclase de UnimplementedError sólo como discriminador
tipado para el shim de E2B (isinstance, nunca el texto).
MountException(message: str, *, code: str)
¶
Bases: SandboxException
Un montaje de mounts= (m15-s3-mounts) falló o sigue sin asentarse.
code es uno de network, iam_denied, not_found, not_allowed,
invalid_path, helper_missing, timeout o unknown (una clase que
el agente manda y este SDK todavía no conoce).
VolumeException(message: str, *, status_code: int | None = None, grpc_code: grpc.StatusCode | None = None, aws_code: str | None = None, code: str | None = None)
¶
Bases: SandboxException
Error de un volumen EFS (m15-efs-volumes, experimental):
VolumeStore.create/get/list/destroy o el estado de volumes= tras
/run.
VolumeMountException(message: str, *, code: str)
¶
Bases: VolumeException
Un volumen de volumes= (m15-efs-volumes) no se montó: create()
ya terminó el sandbox (salvo keep_on_failure). code es uno de
network, iam_denied, not_found, tls, helper_missing,
timeout, invalid_path o unknown (la clase que reporta rayd,
nunca el mensaje del helper).
VolumeNotFoundException(message: str, *, status_code: int | None = None, grpc_code: grpc.StatusCode | None = None, aws_code: str | None = None, code: str | None = None)
¶
Bases: VolumeException
El volumen no existe: VolumeStore.get/destroy sobre un nombre sin
AccessPoint, o el access point o el sistema de ficheros ya no están.
VolumePathNotFoundException(message: str, *, status_code: int | None = None, grpc_code: grpc.StatusCode | None = None, aws_code: str | None = None, code: str | None = None)
¶
Bases: VolumeException
Reservada con el nombre de E2B: esta versión no la lanza. Las
operaciones de contenido de un volumen (read_file/write_file/... del
shim de E2B) no tienen plano de datos propio fuera de un sandbox y son
UnimplementedError.
BuildException(message: str, *, reason: str | None = None, step: int | None = None, command: str | None = None, exit_code: int | None = None, log_tail: str | None = None)
¶
Bases: SandboxException
Template.build (m15-templates) falló: reason nombra la causa
(build_quota, aws_error cuando AWS rechazó el build por otro motivo
—el mensaje y __cause__ llevan sólo el resumen saneado—,
ready_client_error, ready_server_error, o None con
step/command/exit_code/log_tail cuando falló un paso del
Dockerfile compilado).
TemplateException(message: str, *, status_code: int | None = None, grpc_code: grpc.StatusCode | None = None, aws_code: str | None = None, code: str | None = None)
¶
Bases: SandboxException
Template (m15-templates): un nombre o un tag inválido, o una
imagen anterior a 0.6 pasada a Sandbox.create() con un Template.
StackException(message: str, *, code: str)
¶
Bases: SandboxException
Un OptionalStacks.deploy/status/destroy (M15 foundations) falló.
code es blocked (pila en ROLLBACK_COMPLETE, hay que borrarla
antes), not_found, in_progress o failed; el mensaje nunca repite
el de CloudFormation.
WebhookException(message: str, *, status_code: int | None = None, grpc_code: grpc.StatusCode | None = None, aws_code: str | None = None, code: str | None = None)
¶
Bases: SandboxException
LifecycleEvents (m15-events-webhooks) no pudo leer o escribir en su
pila (webhooks, eventos o la clave), o create(events=) sin la pila
desplegada; el mensaje nunca repite una URL ni un secreto.
DashboardException(message: str, *, status_code: int | None = None, grpc_code: grpc.StatusCode | None = None, aws_code: str | None = None, code: str | None = None)
¶
Bases: SandboxException
Una llamada de lectura del panel de gestión (Service Quotas, Cost
Explorer, imágenes) falló con un código de AWS sin excepción propia;
aws_code lo lleva y el mensaje nunca repite el de AWS.
CustomDomainException(message: str, *, status_code: int | None = None, grpc_code: grpc.StatusCode | None = None, aws_code: str | None = None, code: str | None = None)
¶
Bases: SandboxException
CustomDomain (m15-custom-domain, experimental) falló: una llamada
al KeyValueStore de register()/refresh()/unregister(), o una de
ellas sin el KvsArn de la pila (pásalo al construir o llama antes a
status()/deploy()). Los fallos de la pila en sí son
StackException.
AgentException(message: str, *, reason: str, session_id: str | None = None, usage: TokenUsage | None = None, exit_code: int | None = None, detail_code: str | None = None)
¶
Bases: SandboxException
Una ejecución del agente de IA (sbx.agent.run(), ai-agent-core)
falló. reason es una lista cerrada: model_error (el proveedor
devolvió un error; detail_code lleva su clase, APIError),
runtime_error, runtime_missing (la imagen no tiene el runtime), protocol_error, timeout,
max_steps, token_budget (en estos dos el SDK para el runtime),
aborted o busy (otra ejecución en curso en el mismo sandbox).
runtime_version_mismatch y output_limit están reservados: hoy no se
emiten. usage son los tokens consumidos hasta el fallo. El mensaje
sale de una tabla fija por reason: nunca lleva el texto del
proveedor, el prompt ni contenido del sandbox.
AgentCoreException(code: AgentCoreErrorCode, **fields: object)
¶
Bases: Exception
--target agentcore (ADR-031) falló antes o durante el despliegue, o
una llamada a un agente de AgentCore no se pudo hacer. code es una lista
cerrada (rayito._agentcore._errors.AgentCoreErrorCode: región o nombre no
válidos, opciones que no aplican, pila, imagen o runtime bloqueados o
fallidos, permisos...) y exit_code el código de salida de la CLI (2
uso o entorno, 1 fallo de AWS). No es un SandboxException: nada de esto
es atribuible a un sandbox. El mensaje sale de una tabla fija en español y
nunca lleva un ARN, una URL, un token ni el texto crudo de AWS; fields
son los valores que interpola.