Error codes and what to tell your usersHome & Business
Every refusal and failure the printing API returns, what caused it, and a plain sentence to show the person at the counter.
Things go wrong in two different places, and your app sees them differently:
- Refusals happen when you send a job. You get an HTTP error status straight away, and nothing was queued.
- Failures happen later, at the bridge or the printer. The job's status becomes
failed, with anerrorCode.
Every error carries an error field: a sentence written for people. If you don't have your own wording, show that. A few 400 messages are aimed at developers, like "payloadB64 is not valid base64". Those mean a bug in the app, not something for staff to fix.
Refusals when you send a job
| Status | code | Cause | Tell your user | Fix |
|---|---|---|---|---|
409 | stock_mismatch | The printer has different labels recorded as loaded | "The wrong labels are in printer. Load labels and try again." | Swap the roll, or press Swap roll on the printer's card to match. Admins were emailed |
409 | stock_unknown | Nothing is recorded as loaded in that printer | "Laberty doesn't know what's in printer yet. Ask an admin to set it." | Choose In it now on the printer's card (Printers & stock) |
422 | wrong_kind | The job doesn't suit the printer: a receipt to a label printer, a PDF to a receipt printer | "That printer can't print this. Choose a different printer." | Choose the printer by type. The response lists what it accepts |
400 | unknown_stock | No label size matches the stock you sent | "Laberty doesn't know that label size." | Use a code from Printers & stock |
400 | Missing or invalid body, lines or payload, or an account with no printers | "Something went wrong sending that. Please tell your admin." | Fix the request. The error says what's wrong | |
404 | The printerId doesn't exist in this account | "That printer isn't set up in Laberty any more." | Fetch GET /api/printers again | |
413 | The payload is over about 1 MB | "That label is too large to print." | A label is a few KB. Check what you're sending | |
429 | Over 60 jobs a minute for the account | "Printing a lot at once. Retrying in a minute." | Wait Retry-After seconds, then retry with the same Idempotency-Key | |
401 | The key is missing, mistyped or revoked | "This app can't reach Laberty. Please tell your admin." | Make a new key | |
403 | Wrong kind of key for that call, or the plan doesn't include it | "This app isn't allowed to do that. Please tell your admin." | See API keys explained |
Failures reported after a job was queued
Check GET /api/print/{id}. When status is failed:
errorCode | What happened | Tell your user | Admins emailed? |
|---|---|---|---|
stock_mismatch | The printer reported different labels from the job's | "Wrong labels in the printer. Load the right ones and print again." | Yes |
no_media | The printer has no labels | "The printer is out of labels." | Yes |
printer_error | Cover open, jam, and so on. error says which | "The printer needs attention: error." | Yes |
unreachable | The bridge couldn't reach the printer | "Laberty can't reach the printer. Is it switched on?" | Yes |
no_address | The printer has no IP address in Laberty | "This printer isn't fully set up yet. Ask an admin." | Yes |
null | Anything else | Show the error text | No |
For the first three, nothing was printed: fix the printer, then send the job again with a new Idempotency-Key.
Admin emails are limited to one per printer per problem per half hour, however many jobs fail.
When a job never finishes
- Stays
queued: the bridge isn't picking jobs up. It may be stopped, or its computer asleep. Tell the user "The printer hasn't picked this up. Is the print bridge running?" CheckGET /api/agent/statusor the Print bridge page. - Stays
claimed: the bridge took the job and then stopped. Once a job has been claimed for 15 minutes, Laberty puts it back in the queue the next time a bridge asks for work, so it prints when the bridge is running again. Don't send it again as well, or it prints twice.
Messages worth copying
Short, specific, and saying who should act:
- Staff can fix it: "Load Large Address labels in the kitchen printer, then press Print again."
- An admin must fix it: "This printer isn't set up in Laberty yet. Please tell your manager."
- Nobody needs to act yet: "Sending to the printer…", then "Printed."
For the causes behind each code, see Wrong-label protection and Nothing printed.
Still stuck?
Contact support and tell us what you tried. We reply by email, usually within 1–2 business days.