Errors

The API uses conventional HTTP status codes. 2xx means success. 4xx means the request was rejected (and usually shouldn't be retried unchanged). 5xx means something went wrong on our side.

Error bodyCopy Anchor Link

Every error response has a JSON body with a human-readable error message and an optional machine-readable code:

{
  "error": "vm not found",
  "code": "not_found"
}

Always branch on the HTTP status code first; treat code as a stable hint and error as a message for logs and humans. The one exception is 503, where the code tells a capacity refusal from a fault (see Capacity refusals).

Status codesCopy Anchor Link

RetryingCopy Anchor Link

# Example: GET a VM, retrying on 429, a 5xx or a dropped connection, up to
# 5 attempts with exponential backoff and jitter. Returns non-zero on failure.
get_vm() {
  local attempt delay status
  for attempt in 1 2 3 4 5; do
    status=$(curl -sS -o vm.json -w '%{http_code}' \
      "https://api.openrelay.inc/v1/vms/$VM_ID" \
      -H "Authorization: Bearer $OPENRELAY_API_KEY")
    case "$status" in
      2??) return 0 ;;
      429|5??|000) ;;  # retryable
      *) echo "GET failed with HTTP $status" >&2; return 1 ;;
    esac
    if [ "$attempt" -lt 5 ]; then
      delay=$((1 << attempt))              # 2, 4, 8, 16 seconds
      sleep "$((delay + RANDOM % delay))"  # plus up to as much again in jitter
    fi
  done
  echo "GET still failing after 5 attempts (HTTP $status)" >&2
  return 1
}

get_vm || exit 1

Idempotent createsCopy Anchor Link

A create that timed out or lost its connection may still have gone through, so repeating it can make a second VM. Send an Idempotency-Key header, a value you choose once per create (1 to 512 bytes, such as a UUID), and send the same key and the same body on every retry: the create runs once.

curl -X POST "https://api.openrelay.inc/v1/orgs/$ORG_ID/vms/create" \
  -H "Authorization: Bearer $OPENRELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f6c1d2e-8a4b-4c3d-9e1f-5a6b7c8d9e0f" \
  -d '{"name":"cuda-devbox","gpuModelId":"rtx-4090","gpuCount":1,"sshKeyIds":["key_2f9c1a"]}'

It applies to these creates:

• Keys are scoped to your organization and the operation. Two API keys of one organization share them, and the same key sent to a VM create and to a pod create makes one of each.
• What counts as the same body. A VM or pod create compares the fields it reads: the same fields and values in another order or with other whitespace are the same request, and a field the API does not know is ignored. A batch create compares the bytes you send, so keep the bytes of the first attempt.
• A repeat is still authorized. It answers only to a caller that may make the create (a read-only key gets its 403, not the stored answer); a batch create also passes the balance check first.
• A request still running after its process stopped holds the key for at most two minutes; a repeat after that runs the create again.
• The key is counted in bytes, not characters: 512 ASCII characters fit, fewer characters of a multibyte script do.
• File uploads (POST /v1/files) take no key: a repeated upload stores a second file, which costs nothing until a batch runs it.

Capacity refusalsCopy Anchor Link

A 503 with one of the codes below means the request is valid, but there is no capacity for it right now. Sending the same request in a loop does not make room. These codes read live fleet availability, so they can clear as nodes and VMs turn over. The Retry-After header on these responses is deprecated: don't depend on it.

The restart codes (VM_NODE_BUSY, POD_NODE_BUSY, and INSUFFICIENT_IP_CAPACITY on a pod start) behave differently from the create codes. A stopped VM or pod is pinned to the node that holds its disk or volume, so a different shape does not help: the refusal clears when that node frees capacity.

Account and balance refusalsCopy Anchor Link

The codes below refuse a request because of the account, not the request or the key: the balance is too low, the account is under review, or it is being verified. All of them are 403s except TOO_MANY_PAYMENT_ATTEMPTS, which is a 400. A new API key or a wider scope clears none of them. In the table, a new workload is a VM or pod create, or a VM fork.

The account is checked before the balance: a new workload on an account that is being verified and whose available balance is under $0.50 is refused with ACCOUNT_PENDING_VERIFICATION, because adding funds would not lift the hold. ORG_SUSPENDED and ORG_DISABLED are returned when the request is authenticated, before it reaches the action, so any authenticated endpoint can return them.

Two more 403s are about the signed-in user rather than the organization. EMAIL_UNVERIFIED refuses every request made with a dashboard session whose email address is not confirmed: confirm it from the confirmation email, then sign in again. API keys are not affected. ORG_LIMIT refuses an organization create when you already own five organizations; contact support if you need another. An account creates at most one organization every ten seconds, and a create inside that window answers 429 ORG_CREATE_IN_PROGRESS: retry after Retry-After.

A card save can also end without the card. Your bank may be asked to confirm a new card, and if it does not, the card is removed and the save answers CARD_NOT_VERIFIED: add a different card. A card form started while a newer one was opened for the same account answers 503 SETUP_INTENT_SUPERSEDED: start the card form again. A second card the bank does not confirm puts the account on verification (ACCOUNT_PENDING_VERIFICATION).

The inference API refuses billable requests from a restricted account, or one being verified, with its own codes: see Inference errors.

PermissionsCopy Anchor Link

In an organization with permissions enabled, a 403 that a role, key restriction or policy decided names the action it needed, the layer that refused it, and the deciding policies, and the OpenRelay-Required-Permission header carries the action:

{
  "error": "This API key is limited and does not include compute.create (Compute: Manage).",
  "code": "FORBIDDEN",
  "permission": "compute.create",
  "deniedBy": "key",
  "policies": ["key:k_9f2:permissions"]
}

deniedBy is role (the role does not grant it), key (the key's restrictions), org_policy (a guardrail or Cedar policy of your organization) or platform (a platform rule, such as another organization's resource or an action only a signed-in session may take). Ask an admin for a role or key that grants the permission, or explain the decision with the access checker. Without permissions enabled, a 403 FORBIDDEN names no permission: see Legacy scopes.

The inference API reports a permissions denial in its own error shape, 403 with type: permission_error: code permission_denied (with permission and denied_by), or model_not_allowed (with model and denied_by) when the model is outside the key's, role's or organization's model list.

Sizing a GPU VMCopy Anchor Link

A GPU VM is sized from the host capacity its GPUs come with, not from a machine tier. Three codes are specific to that:

An explicit request is capped at one node's per-GPU share times the GPU count, so a one-GPU VM cannot take a multi-GPU node's whole host. Auto sizing takes the tightest node that can still give a full share, which keeps RAM-rich nodes available to larger counts. The floor is 65% of the VRAM the VM is placed against for guest RAM. The boot disk defaults to 100 GB per GPU and its only floor is the flat platform minimum, so a smaller disk is a valid request.

Diagnosing failuresCopy Anchor Link

For resources that can land in a failed or stuck state (VMs and pods), the resource body carries a statusReason field with a human-readable cause: read it before retrying a create.