Skip to content
LabelZoom Docs

Errors

The LabelZoom API returns standard HTTP status codes and a JSON error body.

Status codes

Section titled “Status codes”
Status Meaning Retry?
200 Success. No
202 Cloud Print accepted a template print. No
400 Invalid parameters, a label that doesn’t parse, a mismatched Content-Type or Accept, or an empty body. To check ZPL, use the ZPL viewer. No
401 Cloud Print: a missing or invalid key, or a dashboard-only operation. Conversion: a URL-to-ZPL conversion without a key; otherwise a bad key converts anonymously. See Authentication. No
403 A paid feature on the free tier, a key without the required scope, or another account’s printer. No
404 An unknown conversion path, printer, job, or template, or a labelIndex out of range. No
406 Accept names a media type the API never returns. Send Accept: */* or the target’s media type. No
409 Cloud Print: an account limit. Check code. No
413 Cloud Print: the document or batch is too large. Check code. No
415 A form or multipart body, or a missing Content-Type: application/json where it’s required. No
422 Cloud Print: the request can’t be carried out as sent. Check code. No
429 A rate limit or the daily print limit. After Retry-After
500 Server error. Yes
502 A conversion or render failed. Yes
503 The API is overloaded. After Retry-After

Error body

Section titled “Error body”

An error body is JSON with a human-readable message; rate-limit responses use error instead. Cloud Print errors that you can act on also include a code:

{ "message": "copies must be a whole number from 1 to 9999" }

Log the message, and branch on the status code and code, never on the message text.

Error codes

Section titled “Error codes”
code Status Fix
agent_limit_reached 409 Remove an agent in the dashboard. Unused enrollment codes hold a slot until they expire.
printer_limit_reached 409 Remove a printer in the dashboard.
payload_too_large 413 Send a smaller document.
batch_too_large 413 Split the template batch.
daily_job_limit_reached 429 Wait for Retry-After. The limit resets at 00:00 UTC.
print_rate_limited 429 Wait for Retry-After.
agent_update_required 422 An agent that serves the printer can’t print copies. Update the agent.
idempotency_key_reused 422 The key was used for a different request. Use a new key.

For the limits behind these codes, see Cloud Print limits.

Request ID

Section titled “Request ID”

Conversion responses include an X-LZ-Request-ID header. Include its value when you contact support. Cloud Print responses don’t include it.

Retry failed requests

Section titled “Retry failed requests”

To retry a failed request:

  1. Retry only 429, 5xx, and network errors. Any other 4xx fails the same way again, so log the response body and fix the request.
  2. If the response has a Retry-After header, wait that many seconds.
  3. Otherwise, back off exponentially (1, 2, then 4 seconds), and stop after 3 retries.
  4. If 5xx errors continue, check status.labelzoom.com and contact support with the X-LZ-Request-ID.

To retry a Cloud Print request without printing twice, send an Idempotency-Key.

What’s next

Section titled “What’s next”