Reliability
Machines sleep, networks drop, and someone always unplugs the label printer to charge a phone. This page describes exactly how RocketPrint behaves when that happens — including the failures we cannot see.
Job states
Every job you create is persisted before we try to print it, so there is always something to query — even if every downstream thing fails.
Transitions are one-way. A completed job cannot become printing again, and a failed job cannot become completed — enforced in the service, not by convention.
Offline queueing
This is the behavior that separates a print API from a print request. If the station is not there when you call, the job waits for it.
The request succeeds. The job is persisted as pending and your application carries on. There is nothing to retry and no error to handle.
When the agent reconnects and re-registers its printers, queued jobs dispatch automatically in the order they were created.
What it does not protect you from is a station that has been off for hours — that becomes a flood of stale labels on reconnect. Cancel what you do not want first.
Idempotency
Duplicate prints are the most expensive failure mode in fulfillment — two labels on one box is a mis-ship. Idempotency is enforced twice, in two different places.
$ curl -X POST https://rocketprint.io/api/v1/print-jobs \
-H "X-API-Key: $ROCKETPRINT_KEY" \
-H "Idempotency-Key: order-1042-label" \
-H "Content-Type: application/json" \
-d '{"printerId":"prn_x1","contentType":"raw_base64","content":"XlhBLi4uXlha"}'
HTTP/1.1 201 Created
{ "id": "job_abc123", "status": "sent" }
# your worker times out and retries the identical request
HTTP/1.1 200 OK
Idempotency-Replayed: true
{ "id": "job_abc123", "status": "printing" } # the same job — nothing printed twiceAn Idempotency-Key is scoped to your organization and API key. An identical retry returns the original job with 200 and Idempotency-Replayed: true. A different payload under a key you already used is rejected with 409 rather than silently printing something new.
Send the header on every create. It costs nothing when it is not needed.
The agent keeps its own ledger of jobs it has claimed and finished, and that ledger survives a restart. If the same job arrives again — after a reconnect, a crash, or a redelivery — the agent replays its recorded outcome instead of printing again.
This is the layer that protects you when the failure is in the middle of the system rather than in your worker.
Limits and back-pressure
300 requests per minute per API key, with a burst allowance of 30. Over the limit you get 429 and a Retry-After header telling you when to come back — not a dropped request.
Content is capped at 10 MiB, and the request body at 14 MiB. Oversized requests return 413 immediately rather than failing halfway through a print.
Jobs dispatch to a station in creation order. Two jobs sent to the same printer within milliseconds print in the order the API accepted them.
GET /v1/print-jobs returns newest-first with a default of 50 and a maximum of 200 per request, filterable by status and printer.
Blind spots
Every print system has these. Most vendors do not write them down.
The print command succeeds before the media runs out. completed cannot tell you that the last label came out blank.
A dirty printhead produces an unscannable barcode and a perfectly successful job. Only a scanner downstream will catch it.
We can tell you a label printed. We cannot tell you it made it onto the right box.
For PDF and text, the station's own driver decides scaling and margins. Raw content avoids this entirely — which is why we recommend it for labels.
Questions
The job stays in its last known state until the agent reconnects and reports the outcome. On reconnect the agent consults its local ledger: a job it already completed is reported as completed rather than printed again.
Queued jobs persist until they are dispatched or canceled. If a station is down for a day, a day of jobs will print when it comes back — which is usually not what you want for time-sensitive labels. Cancel what is stale before bringing a long-offline station back online.
Yes, while it is still pending. Once a job has been dispatched to an agent it is no longer cancelable and the request returns a conflict.
The job moves to failed and carries an error string describing what happened — the queue rejected it, the printer was unreachable, the format was not supported by that device. The job stays queryable so you can build alerting on it.
Not yet. Job status is polled today, either directly or with the Node SDK's waitFor helper. Webhooks are on the roadmap; we will announce them on the changelog when they ship.
Build against the real contract
Every state, header, and limit on this page is in the API reference too.