Behavioral differences

Authentication, error codes, rate limits, and the gaps to check before you change production traffic

Check each item against your integration before you change production traffic.

Authentication

	Labelary	zpl.tools
Key required?	No — free tier works with no key	Yes, on every request
How keys are issued	Email-based signup for a premium key	Create a scoped key from your account
Key scope	Single tier (free/premium)	Keys are scoped to PNG only, PDF only, or all formats

The API returns a 403 with a structured body if a request with a png-scoped key resolves to PDF via Accept, or the reverse. See Error Reference.

Rate limits and throughput

	Labelary	zpl.tools
Rate limit	3–10 requests/sec depending on tier, plus daily caps	No default rate limit — optional soft limits (`requests/sec`, `pages/day`) can be set per key
Page count per request	50 labels max	Unlimited
Request body size	1 MB	Unlimited
Image file size	200 KB	Unlimited

You can remove the logic that paces requests below Labelary's limits. A platform abuse limit applies to each organization, and normal traffic does not reach it.

Both services report a render error from bad input or bad ZPL as text/plain with an ERROR: prefix. The messages are similar, but not identical in every case. This service reports an authentication or authorization error (401, 403, or 429) as a JSON envelope, which Labelary never returns.

Case	Status	Notes
Invalid `dpmm`	`400`	Same message shape (`Unknown print density N; valid values: 6, 8, 12, 24`)
Label too large / too small	`400`	zpl.tools' floor is `0.001"`; distinct messages for too-small vs. too-large
Index out of bounds	`404`	Same ordinal phrasing (`Requested 2nd label but ZPL only generated 1 label`)
No labels rendered	`404`	Message depends on whether an index was requested — see Error Reference
Unsupported `Accept` value	`406`	Both services reject with `406`; zpl.tools also returns `406` for formats Labelary supports and this API does not render (see below)
Malformed ZPL	Differs — see below	Not yet verified byte-for-byte against live Labelary; see below
Invalid API key	`401` (zpl.tools only)	No Labelary equivalent (key is optional there)

Full reference: Error Reference.

Default render behavior

X-Quality: Both services default to Grayscale, so this value requires no change. The API implements Bitonal, which thresholds the grayscale render to pure black and white.
X-Rotation: The API implements this header for PNG output: 0/90/180/270 rotate the image clockwise, as Labelary does. The API does not rotate PDF output yet. For PDF with rotation, render PNG instead, or do not migrate that call yet.

Malformed ZPL

The renderer ignores an unknown or invalid command and renders the rest of the label, as a physical Zebra printer does.

A submission with no recognizable ZPL renders zero labels: plain text, or ^XA^XZ with nothing between the two commands. The API returns a 404 status that states that no labels were generated, not a 500 status.

We did not verify the Labelary behavior on fully unparsable input against a live Labelary call. If your integration depends on this case, verify it against both services first.

PDF page-layout headers

The API accepts and validates these headers: X-Page-Size, X-Page-Orientation, X-Page-Layout, X-Page-Align, X-Page-Vertical-Align, and X-Label-Border. The validation matches Labelary's: the API rejects an unknown value with a 400. A label that does not fit the requested page or layout gets the same "not enough room" error.

These headers do not change the rendered PDF yet. The renderer sizes the page to the label, not to Letter or A4, and does not arrange multiple labels into a grid. If your integration depends on a letter-size PDF page or an N-up layout, contact zpl.tools before you migrate that part.

Formats not implemented

Labelary supports several formats that this API does not render. A request for one gets a 406, not a 200:

application/json: label-data extraction, which parses the ZPL fields into structured data, not an image.
application/epl, application/ipl, application/dpl, application/sbpl, application/pcl5, and application/pcl6: alternate printer languages.
POST /v1/graphics (image to ZPL, EPL, IPL, DPL, SBPL, or PCL) and POST /v1/fonts (TTF font to ZPL font). Neither utility endpoint exists in this API.

If your integration requires one, contact us.

Path parameter details

dpmm: Both services accept the suffixed form 8dpmm and the bare number 8.
Dimensions: The API accepts 0.001–15 inches, and rejects a value outside that range with a 400 that names the bound, too small or too large.