Node API Error Codes and Retry Advice

When a node returns a JSON error, inspect its error code alongside the HTTP status and the operation you requested. This reference explains the current codes and recovery options. A connection failure or unreadable response is a separate, uncertain outcome; it does not establish whether a print reached the printer.

Two envelopes

Most routes answer with an error envelope: ok, error, and an optional free-text detail.

{
  "ok": false,
  "error": "image_digest_mismatch",
  "detail": "X-PN-Image-Sha256 must be 64 hex characters"
}

The three command routes — POST /print, POST /drawer/kick, POST /raw — answer a command result instead, which carries commandId and endpoint alongside the same error string. Its status is derived from the code rather than chosen per call site: 422 for unknown_endpoint, render_too_large and unsupported_line_type — the job's shape or size, which only the caller can fix — and 409 for everything else. Every one of those outcomes is also mirrored onto the /events stream as a command_result with the same error, so a POS watching the stream and the one that made the request see the same story.

Not every refusal on those three routes is a command result. A body that does not parse, a raw payload past its cap, or a raw decode buffer the node could not allocate is refused before any command exists, and answers with the plain error envelope — no commandId, and nothing on /events. POST /compose always answers with the plain envelope, including for the printer refusals it shares with POST /print.

detail is for a human. It is optional, it is free text, and it is not a second machine-readable field — do not parse it.

The rule, before the table

• 409 and 503 often describe temporary state. Inspect the error code and delivery outcome before retrying.
• 400, 404, 413 and 422 need the route-specific explanation. A malformed command must be fixed, but invalid_body can also mean a failed body read, and a missing boot-log record is different from an unknown route.
• 401 needs a credential. See auth.
• 500 means the operation failed. Configuration or storage writes may have partially changed state. Follow the code-specific recovery instructions before repeating a mutation.

The exceptions are all in the table, and there are two worth knowing before you write the branch: unknown_endpoint is a 409 on /compose and a 422 everywhere else, and render_alloc_failed is a 409 on /print and /compose and a 503 on /raw despite reading like a request problem — an explicit allocation refusal can be retried after capacity recovers. A timeout or missing response does not establish that the request failed before output.

Print outcomes and retries

Command IDs correlate results; the device does not deduplicate repeated IDs. A successful command response means transport acceptance, not proof that a complete receipt emerged. After a timeout, disconnect or write_failed, bytes may already have reached the printer. Do not automatically retry print, raw, drawer or compose mutations: inspect the paper and let the operator authorize a clearly marked reprint with a fresh ID. A later status read cannot establish the earlier outcome. The table's retry column describes whether the condition may clear, not a blanket replay policy.

The codes a node can send

Two that look alike and are opposites

409 restart_pending is transient, and it fires on a node nobody touched. Asking for an update check or an apply is refused while a restart is already held — and the gate has two callers, not one: an installed image waiting for a quiet moment, and the USB recovery ladder’s reboot rung. The deadline is 900 seconds, so the window can stand for up to fifteen minutes. Retry works. This branch used to answer cloud_not_configured for the same condition, which was harmless while an update was the only thing that could hold a restart and actively misleading once the recovery ladder could ask for one too: a node that had never seen an update told its operator the cloud was unconfigured.

422 image_digest_mismatch is permanent. Every declared byte arrived and hashed to something other than the digest the caller promised — or the digest header was present and malformed. Retrying the identical bytes never works. It is split out of image_invalid precisely so it does not read as "wrong file": nothing is wrong with the file that was chosen, and what to go and look at is the transfer, or the artifact behind it.

Where this list comes from

The codes are read from the shared protocol package, which firmware, the digital twin, this site and the tooling all compile against. A contract check compares that list against the string literals the firmware actually passes to its error helpers, and fails both ways — a code the firmware emits that the list does not declare, and a code the list declares that no handler produces. That is what keeps a vocabulary from becoming a wish list.

Try the codes before you have hardware: the digital twin uses the same envelopes on the routes it implements, and its fault-injection plane can produce paper-out and cover-open, which a real node reports as printer status rather than as a refusal. It does not implement every route — see the API overview for the gaps — so a code that only a missing route emits has to be met on hardware.

Still stuck? Contact support with your node model, firmware version, and what happened. Include an error code if you have one.