Node API Error Codes and Retry Advice

Every failed response from a node carries an error string, and that string is the only part of the response your software should branch on. This page is the whole vocabulary: what each code means, which HTTP status it arrives on, which routes emit it, and — the column to read first — whether sending the identical request again can ever work.

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 and render_too_large, 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.

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

If you want one sentence rather than forty rows:

• 409 and 503 describe the node’s current state. Worth retrying.
• 400, 404, 413 and 422 describe your request. Retrying identical bytes will not help.
• 401 needs a credential. See auth.
• 500 means the node took the request and failed itself. The two profile_* codes want a reboot rather than a retry.

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 despite reading like a request problem — the job was fine and the node was out of heap.

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 answers on the same routes with the same envelopes, 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.