export declare class PlatinumError extends Error {
    readonly status: number;
    readonly body: unknown;
    /** Machine-readable error code from the API body (e.g. `sandbox_not_running`). */
    readonly code?: string | undefined;
    constructor(status: number, body: unknown, message: string, 
    /** Machine-readable error code from the API body (e.g. `sandbox_not_running`). */
    code?: string | undefined);
    /** The Idempotency-Key the failed request carried, when it sent one. When
     *  the outcome is unknown (a lost response, timeout or 5xx), resend the call
     *  with the same key to recover the same operation. */
    idempotencyKey?: string;
}
/** 400 / 422 — the request body or params failed validation. `body` carries
 *  the API's structured detail (zod issues) — print it when debugging. */
export declare class ValidationError extends PlatinumError {
    constructor(status: number, body: unknown, message: string, code?: string);
}
/** 401 — missing/invalid/revoked API key. */
export declare class AuthenticationError extends PlatinumError {
    constructor(status: number, body: unknown, message: string, code?: string);
}
/** 403 — authenticated but not allowed (scope or role). */
export declare class ForbiddenError extends PlatinumError {
    constructor(status: number, body: unknown, message: string, code?: string);
}
/** 404 — sandbox/template/resource does not exist (or was deleted). */
export declare class NotFoundError extends PlatinumError {
    constructor(status: number, body: unknown, message: string, code?: string);
}
/** 409 — valid request, wrong state (e.g. `sandbox_not_running`, name taken,
 *  operation already in progress). Inspect `.code` to branch. */
export declare class ConflictError extends PlatinumError {
    constructor(status: number, body: unknown, message: string, code?: string);
}
/** 429 — rate limited. The SDK never auto-retries (by contract); back off
 *  using `retryAfterSeconds` when the server provided it. */
export declare class RateLimitError extends PlatinumError {
    readonly retryAfterSeconds?: number | undefined;
    constructor(status: number, body: unknown, message: string, code?: string, retryAfterSeconds?: number | undefined);
}
/** 5xx — the API or data plane failed; the request may or may not have taken effect. */
export declare class ServerError extends PlatinumError {
    constructor(status: number, body: unknown, message: string, code?: string);
}
/** Client-side timeout — the HTTP request was aborted by the SDK's own timer,
 *  or a wait helper (waitRunning/waitState/Template.build) hit its deadline.
 *  status is always 0. */
export declare class PlatinumTimeoutError extends PlatinumError {
    constructor(body: unknown, message: string, code?: string);
}
/** The CONTROL PLANE cannot do an atomic replace: it has no
 *  `PUT /v1/sandboxes/{id}/files/atomic` route, so it answered the route itself
 *  with a 404.
 *
 *  This is deliberately NOT a silent downgrade. An atomic replace asked for as
 *  a query flag on the ordinary write would have been IGNORED by an older
 *  control plane, which would then have performed the in-place write the caller
 *  was trying to avoid and returned 200 — and by the time the caller could
 *  check anything, the unsafe write had already happened. A separate route
 *  cannot be misread that way: it is either there or it is a 404.
 *
 *  Distinct from a 409 `atomic_write_unsupported` (a ConflictError), which
 *  means the control plane DOES support it but this sandbox's in-VM agent
 *  predates the guest verb — rebuild the template for that one. Here the fix is
 *  to upgrade the control plane, or to call `files.write()` and accept a
 *  non-atomic in-place write. */
export declare class AtomicReplaceUnsupportedError extends PlatinumError {
    constructor(status: number, body: unknown, message: string);
}
/** Transport failure — DNS, refused connection, TLS, socket reset. status is
 *  always 0; `.cause` carries the underlying runtime error. */
export declare class PlatinumConnectionError extends PlatinumError {
    constructor(body: unknown, message: string, cause?: unknown);
}
/** One process pinning a volume mount: an open fd, cwd, root, mmap or exe. */
export interface VolumeHolder {
    pid: number;
    comm: string;
    kind: 'fd' | 'cwd' | 'root' | 'mmap' | 'exe' | string;
    path: string;
}
/** 404 `volume_not_found`. */
export declare class VolumeNotFoundError extends NotFoundError {
    constructor(status: number, body: unknown, message: string, code?: string);
}
/** 409 `volume_exists` — the name is taken (names are unique per org, case-insensitively). */
export declare class VolumeExistsError extends ConflictError {
    readonly volumeName?: string;
    constructor(status: number, body: unknown, message: string, code?: string);
}
/** 409 `volume_busy`. A pull or detach found processes holding the mount
 *  (`holders`), or a volume delete found live mounts (`mounts`). */
export declare class VolumeBusyError extends ConflictError {
    readonly holders: VolumeHolder[];
    readonly mounts: unknown[];
    constructor(status: number, body: unknown, message: string, code?: string);
}
/** 403 `quota_exceeded`. `limit` says which one: `volumes`, `bytes`, `stored_bytes` (history, tags and pending uploads), `tags` or `mounts`. */
export declare class QuotaExceededError extends ForbiddenError {
    readonly limit?: string;
    readonly max?: number;
    constructor(status: number, body: unknown, message: string, code?: string);
}
/** 409 `read_only_mount` — commit on a mount attached read-only. */
export declare class ReadOnlyMountError extends ConflictError {
    constructor(status: number, body: unknown, message: string, code?: string);
}
/** 503 `commit_failed`. Always retryable; the SDK already retried a few times
 *  before surfacing it. */
export declare class CommitFailedError extends ServerError {
    readonly retryAfterSeconds?: number | undefined;
    readonly retryable: boolean;
    constructor(status: number, body: unknown, message: string, code?: string, retryAfterSeconds?: number | undefined);
}
/** Build the right error subclass for an HTTP status. Folds the API's `code`
 *  and human `error` message into the Error message so logs are actionable
 *  without unpacking `.body`. */
export declare function errorFromResponse(method: string, path: string, status: number, body: unknown, retryAfterSeconds?: number): PlatinumError;