Error codes

Every error has a code, a message and a retryable flag. The agent sends:

{
  "v": 1,
  "id": "c1b2…",
  "type": "response",
  "ok": false,
  "error": { "code": "PRINTER_OFFLINE", "message": "…", "retryable": true }
}

The REST API answers with the matching HTTP status and { "error": { "code", "message", "retryable", "details" }, "requestId" }. Both SDKs throw an error object with the same fields.

Retryable means that sending the same request again may succeed. The agent already retries retryable printer errors itself (5 attempts by default, after 2 s, 5 s, 15 s, 30 s and 60 s).

Code	Retryable	Sent by	Meaning	What to do
`UNAUTHORIZED`	no	agent, cloud	No valid credentials: a missing or revoked API key, an expired session, or a signed request from an organization the agent does not belong to.	Check the API key or the `orgId` and `keyId` your signer uses.
`SIGNATURE_INVALID`	no	agent	The request signature does not verify with any signing public key of the organization.	Sign the exact `params` the SDK sends, with a key that is not revoked. The agent receives new keys with its config.
`SIGNATURE_EXPIRED`	no	agent	The signature's timestamp is more than 300 seconds away from the agent's clock.	Sign each request just before sending it, and check the clocks of both machines.
`NONCE_REUSED`	no	agent	The nonce was already used in the last 10 minutes.	Generate a new random nonce for every request.
`ORIGIN_NOT_ALLOWED`	no	agent	The web page's origin is not in the organization's allowed origins.	Add the origin (scheme, host and port, no path) in Dashboard → Developers → Allowed origins.
`SITE_BLOCKED_BY_USER`	no	agent	In unsigned mode, the person at the computer chose Block for this site.	The choice is stored per origin; it can be reset from the tray menu.
`NOT_ACTIVATED`	no	agent	The agent is not activated, so it has no organization and no keys.	Activate it with an activation code from Dashboard → Devices → Add device.
`LICENSE_LIMIT`	no	agent, cloud	The plan's limit is reached: devices, jobs this month, or a feature not in the plan.	Upgrade the plan or remove unused devices.
`RATE_LIMITED`	no	agent, cloud	Too many requests for this API key, device or origin.	Wait for the `Retry-After` delay (REST) and slow down.
`INVALID_JOB`	no	agent, cloud	The job does not match the job-request schema, or its content cannot be decoded or rendered (including a template that fails to render).	`details` names the field. Validate against `protocol/schemas/job-request.json`.
`UNSUPPORTED_FORMAT`	no	agent, SDK	The agent or the target printer cannot print this job type.	Check `capabilities` in `agent.info` and on the printer.
`PRINTER_NOT_FOUND`	no	agent, cloud	No printer matches the ID, alias or name, or there is no default printer.	List printers first, or set an alias in the device config.
`PRINTER_OFFLINE`	yes	agent	The printer does not answer: switched off, unplugged or unreachable on the network.	The job is retried automatically. Check power, cable and network.
`PAPER_OUT`	yes	agent	The printer reports no paper.	Load paper; the job is retried automatically.
`COVER_OPEN`	yes	agent	The printer reports an open cover.	Close the cover; the job is retried automatically.
`PRINTER_ERROR`	no	agent	The printer reports an error it cannot recover from alone (cutter jam, overheating, spooler error).	Check the printer, then reprint the job.
`JOB_NOT_FOUND`	no	agent, cloud	No job with this ID in this organization.	Check the ID. Local job history is kept for a limited time.
`JOB_ALREADY_FINISHED`	no	agent, cloud	The job is already printed, failed or cancelled, so it cannot be cancelled.	Nothing to do; use reprint to print it again.
`TIMEOUT`	yes	agent, SDK	No answer in time: the printer did not confirm, a queued job passed its TTL, or the SDK got no answer from the agent.	The agent retries printer timeouts. In the SDK, raise `timeoutMs` or retry.
`UPDATE_REQUIRED`	no	agent	The agent is older than the minimum supported version and refuses local jobs.	The agent updates itself; install the latest version by hand if it cannot.
`INTERNAL`	no	agent, cloud	An unexpected error.	Retry later. If it persists, contact support with the `requestId`.
`NOT_FOUND`	no	cloud	The REST resource (device, printer, template, webhook) does not exist here.	Check the ID and that it belongs to the API key's organization.
`FORBIDDEN`	no	cloud	The API key lacks the scope, or the user lacks the role, for this call.	Create a key with the needed scope (for example `jobs:write`).
`CONFLICT`	no	cloud	The request conflicts with the current state, for example the same idempotency key with a different body.	Use a new idempotency key for a different job.
`VALIDATION_FAILED`	no	cloud	The request body or query does not validate.	`details` lists each field and problem.
`AGENT_NOT_FOUND`	no	SDK only	No agent answers on any local port (8182, 8283, 8384, 8485).	Install or start the agent; `helpUrl` points to the download page.
`AGENT_CERT_UNTRUSTED`	no	SDK only	The agent runs, but the browser does not trust its local certificate, so the secure WebSocket fails.	Reinstall the agent so it trusts its local CA again, then restart the browser.

This page is generated from protocol/schemas/error-code.json, the source of the ErrorCodes constants in @jodaprint/protocol.