Errors

When the API refuses a call, it says why in the same shape every time: a code your program can rely on, and words for you.

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json
X-Request-Id: req_01jb2xk3n4p5q6r7s8t9v0w1x2

{
  "type": "https://docs.wheelmachine.ai/errors/forbidden",
  "title": "This key may not do that",
  "status": 403,
  "detail": "this key does not hold the cloud:machines:exec scope",
  "code": "forbidden",
  "request_id": "req_01jb2xk3n4p5q6r7s8t9v0w1x2"
}

Read a refusal#

A refusal is application/problem+json (RFC 9457):

In wm and the libraries#

wm prints the refusal's words, its code, its status and its request id, and exits with 1:

$ wm exec box -- make test
wm: this key does not hold the cloud:machines:exec scope (forbidden, 403, request req_01jb2xk3n4p5q6r7s8t9v0w1x2)

The libraries raise (or throw) a WheelmachineError with status, code, detail, the request id (request_id in Python, requestId in TypeScript) and the wait it asked for (retry_after, retryAfter). Each family of statuses has its own class, the same name in both:

from wheelmachine import PermissionDeniedError, WheelmachineError

try:
    client.machines.exec(machine.id, ["make", "test"])
except PermissionDeniedError as err:
    print("this key may not run commands:", err.detail)
except WheelmachineError as err:
    print(err.status, err.code, err.request_id)

import { PermissionDeniedError, WheelmachineError } from "wheelmachine";

try {
  await client.machines.exec(machine.id, ["make", "test"]);
} catch (err) {
  if (err instanceof PermissionDeniedError) console.log("this key may not run commands:", err.detail);
  else if (err instanceof WheelmachineError) console.log(err.status, err.code, err.requestId);
  else throw err;
}

Try again, safely#

Some refusals pass: rate_limited, unavailable, and conflict while a first call with the same Idempotency-Key is still running. Wait the seconds Retry-After says, then send the call again. The libraries and wm do this by themselves, up to a few times, with a growing wait when none was said. The rest mean the call itself must change before it can work.

A call that makes something (a machine, a copy, a snapshot, a project or a key) can carry an Idempotency-Key header: any string up to 255 printable characters, new for each thing you mean to make. Sent again with the same key and the same request within 24 hours, it gets the first answer again, with Idempotent-Replayed: true, and nothing is made twice. The same key with a different request answers 422 invalid_request. Answers that pass (429 and 5xx) are not kept, so a retry of one runs again. The libraries put an Idempotency-Key on every call that makes something, the same on each of its tries.

curl -X POST https://api.wheelmachine.ai/v1/machines \
  -H "Authorization: Bearer $WHEELMACHINE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: nightly-build-2026-10-23" \
  -d '{"name": "nightly"}'

A command is different: it may already have run, so neither the libraries nor wm ever send one again by themselves.

Every answer carries X-Request-Id. Send your own X-Request-Id (letters, digits, - and _, up to 64) and the API uses it, so a call can be found by the same id in your logs and ours.

Every code#