Errors

All API responses follow a consistent error format. This page lists every error code, its cause, and how to resolve it.

Error response format

{
  "success": false,
  "error": "error_code",
  "message": "Human-readable description of what went wrong"
}

Field	Type	Description
`success`	`boolean`	Always `false` for errors
`error`	`string`	Machine-readable error code
`message`	`string`	Human-readable explanation

Authentication errors

HTTP	Error code	Cause	Fix
401	`unauthorized`	Missing or invalid API credentials	Check `X-Client-ID` and `X-Client-Secret` headers
401	`token_expired`	VM token has expired (30-day TTL)	Generate a new token via the API Access endpoint
403	`forbidden`	Valid credentials but insufficient permissions	Verify you own the VM or have namespace access

Quota & limit errors

HTTP	Error code	Cause	Fix
403	`SANDBOX_LIMIT_REACHED`	Maximum VM count reached for your plan	Delete unused VMs or upgrade your plan
403	`POOL_LIMIT_REACHED`	Owned pool (total resources) exhausted	Reduce resource allocations or delete VMs
403	`RUNNING_POOL_REACHED`	Running pool (active resources) exhausted	Stop a running VM or upgrade your plan
403	`quota_exceeded`	Resource request exceeds plan per-VM limits	Reduce requested CPU, memory, or disk
503	`quota_unavailable`	Plan resolution failed temporarily	Retry the request in a few seconds

Handling quota errors

try {
  await client.vms.start('ws_a1b2c3d4');
} catch (err) {
  if (err.code === 'RUNNING_POOL_REACHED') {
    // List running vms and stop one
    const list = await client.vms.list({ status: 'running' });
    await client.vms.stop(list[0].id);
    // Retry
    await client.vms.start('ws_a1b2c3d4');
  }
}

Resource errors

HTTP	Error code	Cause	Fix
400	`bad_request`	Invalid parameters (e.g., negative CPU, invalid image)	Check request body against the API reference
400	`validation_error`	Request body fails schema validation	Review required fields and types
400	`invalid_image`	Requested image does not exist	Use the Images API to list available images
400	`invalid_resources`	CPU, memory, or disk outside allowed range	Check plan limits on the Pricing page

State errors

HTTP	Error code	Cause	Fix
409	`invalid_state`	Operation not allowed in current VM state	Check VM status before the operation
409	`must_be_running`	Operation requires the VM to be running	Start the VM first
409	`must_be_stopped`	Operation requires the VM to be stopped	Stop the VM first
409	`must_be_paused`	Operation requires the VM to be paused	Pause the VM first

State machine

Valid transitions:

From	Allowed actions
`created`	start, destroy
`starting`	- (wait for running)
`running`	stop, restart, pause, destroy
`stopping`	- (wait for stopped)
`stopped`	start, destroy
`paused`	resume, destroy

Not found errors

HTTP	Error code	Cause	Fix
404	`not_found`	VM ID doesn't exist or was deleted	Verify the VM ID; it may have been auto-deleted (TTL/remove_on_exit)
404	`snapshot_not_found`	Referenced snapshot doesn't exist	List snapshots to find valid IDs
404	`workload_not_found`	Referenced workload doesn't exist	List workloads to find valid IDs

VM errors

HTTP	Error code	Cause	Fix
500	`server_error`	Unexpected error in the VM backend	Retry the request; if persistent, contact support
502	`vm_unavailable`	VM host is unreachable	The VM may be migrating; retry after a few seconds
504	`vm_timeout`	VM operation timed out	The VM may be under heavy load; retry with backoff

Rate limiting

HTTP	Error code	Cause	Fix
429	`rate_limited`	Too many requests in a short period	Wait and retry with exponential backoff

Rate limits vary by plan. See the Pricing page for current limits.

Handling errors in the SDK

The SDK throws typed errors that you can catch and inspect:

import {
  OblienError,
  AuthenticationError,
  NotFoundError,
  RateLimitError,
  ValidationError,
  PaymentRequiredError,
  ConflictError,
} from 'oblien';

try {
  const result = await client.vms.create({ image: 'oblien/node:24' });
} catch (err) {
  if (err instanceof OblienError) {
    console.error(`[${err.status}] ${err.message}`);

    if (err instanceof PaymentRequiredError) {
      // Handle vm limit / quota
    } else if (err instanceof ConflictError) {
      // Handle state conflict
    } else if (err instanceof ValidationError) {
      // Handle bad params
    } else if (err instanceof NotFoundError) {
      // VM not found
    } else if (err instanceof RateLimitError) {
      // Rate limited - retry with backoff
    } else {
      throw err;
    }
  }
}

Retry strategy

For transient errors (5xx, timeouts), use exponential backoff:

async function withRetry(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (err) {
      const isRetryable = err.status >= 500 || err instanceof RateLimitError;
      if (!isRetryable || i === maxRetries - 1) throw err;

      const delay = Math.min(1000 * Math.pow(2, i), 10000);
      await new Promise(r => setTimeout(r, delay));
    }
  }
}

// Usage
const vm = await withRetry(() => client.vms.create({ image: 'oblien/node:24' }));

The SDK has built-in retry logic for transient errors. You can configure it when initializing the client. See SDK Setup for details.

On this page