Errors

The API uses conventional HTTP status codes. This page is general guidance; the Swagger reference is authoritative for exact response shapes.

Status	Meaning	What to do
400	The label code or file didn’t parse (malformed ZPL, unsupported content), Content-Type doesn’t match the source format, or Accept names a media type this target can’t produce	Check the response body for details; validate the label in the ZPL viewer
401	Missing or invalid API key	Send Authorization: Bearer <key>; check the key in your dashboard
403	Key is valid but the plan doesn’t allow the operation	Compare against your plan’s features
406	Accept names a media type the endpoint never produces	Send the target’s media type, a wildcard subtype such as image/*, or */* — see Supported formats
413	Request body too large for your tier	Files >1 MB need Pro or above
429	Rate limit exceeded	Back off and retry; sustained volume needs a higher tier
5xx	Transient server-side problem	Retry with exponential backoff (e.g. 1s, 2s, 4s); include the X-LZ-Request-ID header value if you contact support

Retry pattern

Treat 429 and 5xx as retryable; treat 4xx (except 429) as permanent — retrying a malformed label will fail forever. A minimal policy:

1. On 429/5xx: wait, then retry up to 3 times with exponential backoff.
2. On 400: log the response body and the label source — don’t retry.
3. On repeated 5xx: check status.labelzoom.com and contact support with the X-LZ-Request-ID.