Error codes

Every API error is a Kubernetes-style Status object. reason is a stable code, code is the HTTP status, and three extra fields tell you what to do next:

{
  "kind": "Status",
  "apiVersion": "v1",
  "status": "Failure",
  "reason": "InsufficientCredits",
  "code": 402,
  "message": "job \"train-a\" needs a $3.20 hold to start (released when it ends); available $1.10",
  "fix": "nodus billing top-up 20, or lower spec.maxCostUSD",
  "docs": "https://nodus-compute.ai/docs/reference/errors/insufficient-credits",
  "requestId": "req_01j9…"
}

Include the requestId when you contact support. The docs link is the code’s page below, named after the code in lowercase words (InsufficientCredits is insufficient-credits).

AdmissionsPaused Operators paused admissions for this kind; existing objects keep running.

AgentGroupClosed A sealed, canceled, finished or deleting AgentGroup admits no new member runs.

AgentGroupFull An AgentGroup admits at most spec.limits.maxPending unfinished member runs.

AgentRunFinished A run in a terminal phase (Succeeded, Failed or canceled) no longer reads its inbox.

AgentStopped An Agent in the Stopped state refuses new runs; runs already created are not affected.

AlreadyExists A create by name found an object with that name whose spec differs; an identical create returns the object.

ArrearsOutstanding Charges that the org's credits could not cover are unpaid; they block new work until they are settled.

BadRequest The request is malformed: a query parameter, selector or body could not be parsed.

BudgetExceeded A Block budget or a maxCostUSD cap that applies to the object has less room than the action's hold.

CapacityUnavailable No offering that meets the requirements has capacity at the moment.

CloudAccountNotVerified Nodus reads inventory only after it has verified the account's read-only access.

Conflict The object changed after the caller read it (the resourceVersion is stale).

ConnectionNotReady A Connection is usable once a verification passed.

EncryptionFailed The org's encryption key was unavailable; nothing was stored.

EnrollmentTokenInvalid An enrollment token works once, for 24 hours, for the pool it was created for.

Expired The watch position or list continue token is older than the 24-hour change history.

FieldImmutable The update changes a spec field that is immutable after create; the causes list each changed field.

FileTooLarge A file request carries at most 64 MiB; larger data does not go through the files API.

Forbidden The credential is valid but lacks the scope or project access the operation needs.

FunctionCallBatchTooLarge A batch create takes at most 1,000 calls and 8 MiB.

FunctionNotFound The Function does not exist in the project, or it was deleted since the call was prepared.

IdempotencyKeyReused The Idempotency-Key was used in the last 24 hours with a different request body.

ImageBuildUnavailable This deployment cannot build image steps, Dockerfiles or Sandbox snapshots; prebuilt registry images remain supported.

ImageNotFound The tag or digest does not exist in the registry, or the pull credentials cannot see it.

ImageNotReady An imageRef runs the digest the Image built; the Image has none yet.

ImagePullFailed The registry refused the credentials or was unavailable while pinning the image to a digest.

InsufficientCredits The org's available credits do not cover the hold that the action reserves before it starts.

InternalError The server hit an unexpected failure; the request id finds it in the logs.

Invalid The object fails strict decoding or validation; `details.causes` lists every field and reason.

MethodNotAllowed The resource does not support this verb (for example, a read-only kind).

NoSSHKey The Workspace accepts only the SSHKeys named in spec.sshKeys, or every project member's keys when it names none.

NotFound The object, project or path does not exist in this org.

OutputIndexRequired Several indexes of an Indexed Job committed the output; the download must pick one.

OutputNotFound The Job did not commit an output by that name, or not at that index.

PaymentDisputed A card payment on the org is disputed; new work cannot start until the dispute closes.

PaymentMethodRequired New work requires a verified card, including work funded by promotional credit. Adding a card does not charge it.

PaymentsNotConfigured The deployment holds no Stripe key, so it takes no card payments; balances, grants and usage still work.

PaymentVerificationUnavailable Stripe could not confirm the payment method. Existing running work retains its funded holds.

PoolActionNotPending Only a queued, undecided action waits for a decision; it may have expired or been decided by someone else.

PoolActionNotReversible Only an executed drain, undrain or routing change can be reverted, once.

PoolActPaused The pool's kill switch stops every action until it is resumed.

PoolInUse A Pool is deleted only once no Node is enrolled in it and no object names it in spec.placement.pool.

PreconditionFailed The If-Match value no longer matches the compiled spec and price book of a fresh dry-run.

PriceConsentRequired Pool routing and Predict are billed, so turning either on records consent to its current price.

PromoCodeExpired The promo code exists but can no longer be redeemed.

PromoCodeUsed The org has already redeemed the code as often as it may, or the code has no redemptions left.

QuotaExceeded The org or project already uses everything its Quota allows of this counter.

RequestEntityTooLarge The request body is larger than the route accepts (1 MiB for JSON).

RequestInProgress The original request with this Idempotency-Key has not finished yet.

SandboxFailed The Sandbox is in the Failed phase, which is final: status.reason says why.

SandboxNotRunning The Sandbox is being deleted, so no command, file or port request can reach it and none starts it.

SandboxStarting The request needs the Sandbox's container, which is not running yet. A stopped Sandbox is started by the request itself; the answer carries Retry-After.

SecretValueInEnv Secret values reach a Job or Sandbox only through secrets or valueFrom.secretKeyRef, never as literals.

SHA256Mismatch A write with expectedSHA256 found different content than the writer started from, so nothing was written.

StdinBackpressure The process's stdin buffer is full, so the write was refused without losing earlier input.

TooManyRequests The credential sent too many requests of this class; the RateLimit headers show the budget.

TopUpLimitReached An org buys at most $5,000 of credit through Checkout per UTC day.

Unauthorized The request carries no valid credential, or the credential expired.

Unavailable A dependency of the API is temporarily unavailable.

Unsupported The request is well formed but asks for a feature this API does not offer.

UnsupportedMediaType The request body's Content-Type is not accepted; strategic merge patch is not supported.

VolumeBusy A ReadWriteOnce Volume has one writer; another attempt holds its lease.

WorkerNotAllowed Only the Function's own worker attempts, through their ServiceAccount token, can claim its calls.

WorkspaceStarting The Workspace has no running session yet: it is starting, or the request woke it from a stop.

WorkspaceToolUnavailable A browser tool has a preview URL only while the Workspace is running and lists the tool in spec.tools.