Sandbox administration errors, recovery, and environments¶
Operation or failure stage |
Current contract |
|---|---|
List |
Invalid integers return 400/ErrParamInvalid in the handler; service window range violations return 400/SANDBOX_INVALID_SPEC. The service treats limit=0 as 50. The window must satisfy offset+limit+1≤2000. |
Administrator privileges |
403/COMPUTE_RESOURCE_SPEC_FORBIDDEN; directory/shared authorization failures use 503/COMPUTE_RESOURCE_SPEC_ADMIN_UNAVAILABLE. Distinguish these from ordinary sandbox and Genesis administration codes. |
Provider unavailable |
There is no uniform 503 mapping. Unclassified failures may return 500/SANDBOX_ERROR; do not assume a stable upstream error code. |
Network |
unrestricted returns 400/SANDBOX_NETWORK_ALLOWLIST_UNAVAILABLE; host/ports have corresponding SANDBOX_EGRESS_* errors. Failure to save an override may return 503/SANDBOX_NETWORK_STORAGE_UNAVAILABLE. |
Quota |
At least one field must be non-null; counts range from 0 to 100. Invalid override modes or empty updates return 400/ErrParamInvalid. |
Successful deletion and partial failures¶
Success returns HTTP200/OK/msg/data:{}. Within the request, deletion first retains deletion intent and advances cleanup; it is not compute resource asynchronous acceptance with 202. Stages include retiring credentials, stopping compute bindings, removing remote resources, cleaning up Ownership, and deleting binding/reservation records. Later failures retain recovery intent and may follow partial side effects.
Administration reads/lists hide resources being created or deleted by business operations. A 404, disappearance from a list, or absence of remote resources does not prove cross-storage cleanup is complete. Recovery must check the original target, frozen lifecycle identity, and persisted records, with the operator continuing the original cleanup. Repeated DELETE is not guaranteed to return 200; do not recover by creating a replacement ID. Actual Provider deletion completion semantics, cross-database recovery, and restart recovery still require verification in a real environment.
Network updates¶
Completely replaces managed tools and explicit egress. It does not modify internal control-plane channels or network_mode, and an empty array does not mean restore defaults. The Provider is updated before the desired override is saved. Failure at either step triggers an attempt to compensate with the original policy; errors.Join may retain both the original and compensation errors. There is no cross-Provider/database transaction or global concurrency-version guarantee. GET primarily overlays the saved override; it alone cannot establish that the remote policy rolled back. Save the original lists before recovery, and check both the actual Provider policy and persisted state.
Quota updates¶
A transaction locks and reads the target quota before a partial update. Explicit 0 is valid; inherit/enabled/disabled map to response values 0/1/2. Lowering a limit does not evict existing sandboxes. The automatic ephemeral switch and concurrency limits are distinct. Current UpdateQuota does not reject requests early based on whether the Provider is enabled, so a successful write does not establish runtime availability.
These APIs do not provide a complete administration quota GET. Ordinary GET projects only managed current/limit and default network targets; it cannot fully back up ephemeral limits and overrides. Before writing, obtain complete, trusted original values confirmed by the operator. Do not write first and use the response as the original backup. Recovery must confirm that no concurrent administrator change occurred. There is no expected_version, idempotency key, or dedicated rollback contract.