Errors

Every error response uses the same JSON shape. You can switch on error.code to handle each case without parsing prose messages or guessing from status codes.

The shape

{
  "error": {
    "code": "validation_failed",
    "message": "size must be one of the published VM sizes",
    "fields": {
      "size": "unknown size 'gp-7-7'"
    },
    "request_id": "req_01HG7Y3..."
  }
}

Four fields, two always present:

The status code groups errors into families; error.code is what you actually want to branch on.

Status code families

5xx is the only family where a retry might help without you changing anything. For 4xx, the response body tells you what to fix.

Error codes that matter

The full list is long; these are the ones you'll handle most often.

Authentication / authorization

See Authentication for the request shape and rotation flow.

Request validation

State

Rate / quota

rate_limit_exceeded is time-bounded — wait and retry works. quota_exceeded is not — you need to delete a resource or raise the quota.

Server

Handling pattern

async function call(): Promise<VM> {
  const res = await fetch(url, opts)
  if (res.ok) return await res.json()

  const { error } = await res.json()

  // Switch on code, not status — codes are stable, statuses can be ambiguous
  switch (error.code) {
    case 'rate_limit_exceeded': {
      const wait = Number(res.headers.get('Retry-After') ?? '1')
      await sleep(wait * 1000)
      return call() // retry
    }
    case 'invalid_credentials':
    case 'expired_credentials':
      await rotateKey()
      return call()
    case 'state_conflict':
      // Wait for the resource to settle and retry
      await sleep(2000)
      return call()
    case 'validation_failed':
      // Fields are in error.fields — surface them in your UI
      throw new ValidationError(error.fields)
    default:
      // Unknown code, but the family tells us the rough shape
      if (res.status >= 500) {
        // Server-side; safe to retry idempotent ops
        throw new RetryableError(error)
      }
      throw new TerminalError(error)
  }
}

The general rule: switch on error.code, default to handling by status family. New codes added on existing families won't break you — your default case handles them.

Reporting bugs

Every error carries a request_id. When something's wrong on our side (5xx, unexpected behavior), the request_id is what lets us find the call in our logs. Include it in support tickets.

Don't share request_ids publicly (they're not secret, but they let anyone who has them ask us about your account's traffic). Use them in private channels (support, dashboard tickets).

What's next

• Conventions — the rest of the request/response shape.
• Authentication — the auth-error codes in context.
• Rate limiting — the Retry-After mechanics in detail.
• Idempotency — safe-retry pattern for 5xx + 429 cases.