ZPLJetdocs
OpenAPIDashboard

Errors & Limits

Predictable error shapes and the limits you should design around.

Error format

Errors return a non-2xx status and a JSON body with an error field:

{ "error": "conversion failed" }

Status codes

400The body failed validation (e.g. missing zpl, or zpl over 512 KB).
401API key missing or invalid.
402Monthly conversion quota exceeded for your plan.
403Hosting (output:"url") not allowed — data-only plan, or enforced no-retention mode.
429Rate limit exceeded for this key. Retry after the Retry-After header (seconds).
502The engine could not render the ZPL.

Limits

  • ZPL size: up to 512 KB per request.
  • Labels per request: up to 50 (rendered as a multi-page PDF).
  • Hosted file retention: data-mode requests store nothing. Hosted files (output:"url") are kept for retentionDays — up to 3 days (Starter), 30 (Pro), or 90 (Scale).
  • Signed URLs: valid for up to 7 days, even when the file is retained longer.
  • Monthly quota: per plan; exceeding returns 402.
  • Rate limits: per API key; exceeding returns 429 with a Retry-After header (seconds).