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)	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
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.