Reliability
Computers sleep, networks drop, and someone always unplugs the label printer to charge a phone. This page says exactly what RocketPrint does when that happens — including the failures we cannot see.
Job states
We save every job before we try to print it, so there is always something to look up — even if everything after that fails.
expiresInSeconds when you create the job.Jobs only move forward. A finished job never goes back to printing, and a failed job never becomes completed. The one exception is unknown, which a late Station report can settle. That is enforced in code, not just documented. The API reference lists all nine values in one table.
Offline queueing
This is what separates a print service from a print request. If the computer 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 Station app reconnects and reports its printers again, everything queued prints automatically, in the order you sent it.
What it does not protect you from is a computer that has been off for hours. That becomes a flood of old labels when it reconnects, so cancel what you do not want first.
Idempotency
Duplicate prints are the most expensive mistake in fulfillment — two labels on one box means the wrong parcel goes out. We prevent it in two separate 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 belongs to your account and API key. Repeat the same request and you get the original job back with 200 and Idempotency-Replayed: true. Send different content under a key you already used and we reject it with 409 instead of quietly printing something new.
Send the header on every create. It costs nothing when it is not needed.
The Station app keeps its own record of jobs it has taken and finished, and that record survives a restart. If the same job arrives again — after a reconnect, a crash, or a redelivery — it reports what happened the first time instead of printing again.
This is what protects you when the problem is in the middle of the system rather than in your own code.
Limits
300 requests a minute per API key, plus a short burst of 30 on top. Go over and you get a 429 with a Retry-After header telling you when to try again. We never silently drop a request.
Content is capped at 10 MiB and the whole request at 14 MiB. Anything larger returns 413 straight away instead of failing halfway through a print.
Jobs reach a computer in the order you sent them. Two jobs sent to the same printer milliseconds apart print in the order we 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 labels run out. completed cannot tell you the last one came out blank.
A dirty printhead produces a barcode that will not scan and a job that looks perfectly successful. Only a scanner further down the line will catch it.
We can tell you a label printed. We cannot tell you it made it onto the right box.
For PDFs and text, that computer's own driver decides scaling and margins. Printer languages avoid this entirely, which is why we recommend them for labels.
Questions
The job stays where it was until the Station app reconnects and tells us what happened. When it reconnects it checks its own records: a job it already printed is reported as printed, not printed again.
Yes. Each job has a queue deadline, set with expiresInSeconds when you create it (10 seconds to 24 hours, one hour by default). A job that is still waiting when the deadline passes becomes expired and is never sent. If a computer has been off for hours, cancel the jobs you no longer want before you bring it back — otherwise a day of old labels prints at once.
Yes, as long as it has not been sent yet. Once it reaches the Station app it can no longer be canceled.
The job is marked failed and tells you what happened — the printer refused it, could not be reached, or does not handle that format. You can still look the job up, so you can build alerts on it.
Not yet. Today you ask us how a job finished, either directly or with the Node client's waitFor helper. Webhooks are coming, and we will announce them on the changelog.
Build for the real world
Every status, header, and limit on this page is in the API reference too.