Error Reference

The API returns render errors as plain text with a Content-Type: text/plain header, like Labelary. Every plain-text error message starts with ERROR: .

The API returns authentication and authorization errors (401, 403, 429) as JSON.

HTTP Status Codes

400 Bad Request

Invalid request parameters or malformed ZPL code.

Examples:

• Invalid DPMM value, with or without the dpmm suffix: ERROR: Unknown print density 10; valid values: 6, 8, 12, 24
• Label too large: ERROR: Label width is larger than 15.0 inches
• Label too small: ERROR: Label width is less than 0.001 inches
• Invalid rotation: ERROR: Label rotation must be 0, 90, 180 or 270 degrees
• Invalid page size: ERROR: Invalid page size: A3
• Invalid page orientation: ERROR: Invalid page orientation: Diagonal
• Invalid page layout: ERROR: Invalid page layout: 0x3
• Invalid page alignment: ERROR: Invalid alignment: Middle
• Invalid page vertical alignment: ERROR: Invalid vertical alignment: Middle
• Invalid label border: ERROR: Invalid label border: Dotted
• Page too small to fit the label: ERROR: Not enough room to fit 1 label vertically; please adjust page layout, page size, page orientation, label size, or label rotation.

The API validates the X-Page-* and X-Label-Border headers, and does not yet compose the PDF layout. See Behavioral notes. An unrecognized X-Quality value is not an error, and the API uses the Grayscale default.

404 Not Found

Missing or invalid data.

Examples:

• No ZPL content, all-labels endpoint (no index requested): ERROR: no labels generated
• No ZPL content, specific index requested: ERROR: Requested 1st label but ZPL generated no labels
• Index out of bounds: ERROR: Requested 2nd label but ZPL only generated 1 label
• PNG requested on the all-labels endpoint (PNG requires an index): ERROR: HTTP 404 Not Found

406 Not Acceptable

Unsupported Accept header value.

Example:

ERROR: HTTP 406 Not Acceptable

Supported formats: image/png, application/pdf

Authentication & authorization errors

Auth-layer errors use a JSON envelope with a stable machine-readable error code and a human-readable message:

{ "error": "invalid_key", "message": "Invalid API key" }

401 Unauthorized

403 Forbidden

A scope_denied response includes the requested format and the key's configured scope:

{
    "error": "scope_denied",
    "message": "API key scope 'png' does not allow pdf output",
    "required": "pdf",
    "actual": "png"
}

The Accept header selects the output format: application/pdf selects PDF, and anything else selects PNG. Set the key scope on the API Keys page: PDF only, PNG only, or all formats.

429 Too Many Requests

A request over a rate limit returns this. limit_scope is key for your own soft limits and organization for the platform abuse limit.

{
    "error": "rate_limited",
    "message": "Rate limit exceeded: 10 requests/sec per key",
    "limit_type": "requests_per_sec",
    "limit_scope": "key",
    "limit": 10,
    "retry_after_seconds": 1
}

Every 429 carries reset headers:

limit_type is requests_per_sec (resets within seconds) or pages_per_day (resets at midnight UTC).

Fix a failed request

Check each item in order:

1. Wrap each label in ^XA and ^XZ, and close every command.
2. Use the correct endpoint path: POST /v1/printers/{dpmm}/labels/{width}x{height}/{index} for one label, or POST /v1/printers/{dpmm}/labels/{width}x{height} for all labels.
3. Send a dpmm of 6, 8, 12, or 24. The dpmm suffix (8dpmm) is optional.
4. Send a width and a height between 0.001 and 15 inches.
5. Send an index of 0 or greater, and less than the number of labels in the ZPL.
6. Send an Accept of image/png (default) or application/pdf. Any other value returns 406, including formats that Labelary supports.
7. Read the ZPL Documentation for command syntax.