Binary Labels
Download Label returns a successful body as binary, not a JSON envelope. Branch
on HTTP status and actual Content-Type before handling the body.
Declared binary types
The current 200 response declares only application/pdf and
application/zpl; all three ZPL printer resolutions (format 2, 3, and
4) share application/zpl. Stream bytes where your client
supports it; do not log the binary body. Select the local filename yourself:
the public contract does not declare Content-Disposition, a filename, cache
behavior, or storage lifetime.
Protect stored shipping Labels under your application's data policy. Download
Label is the documented binary operation and the one that takes your bearer
credential. The purchase and Get Order responses additionally carry temporary
pre-signed asset links, in labelAssets[] and the flat label URL fields. Those
links download directly from storage with no Authorization header and they
expire, so treat them as credentials rather than durable addresses; see
Buy a Label for their per-format readiness and
lifetime.
Pending response
202 means pending/still generating only. The response carries a Retry-After
header — a whole number of seconds — so wait that long before requesting the
same download again, reading the value from the header rather than hard-coding
it. It is a retry hint for that response: no polling schedule, retry budget,
deadline, or eventual-success guarantee is public. Preserve the identifier,
avoid a tight loop, and keep the surrounding cadence application-owned.
For parameters and documented errors, see Download a Label and Label Errors.