Label Errors
Purchase failures
POST/api/v1/shipments/{shipmentId}/labels
| Situation | Status |
|---|---|
Invalid or no-longer-usable rate id, or other invalid request | 400 |
| Missing or no-longer-usable bearer token | 401 |
Order is already Cancelled, already LabelCreated, or Returned | 400 |
| Purchase still running when the wait window ends | 202 — not a failure; read the Order for the outcome |
| A different purchase is in progress, or the Shipment already has a Label | 409 |
| The rate, its Shipment, or the Order behind it does not exist for your account | 404 |
| The carrier rejected the Shipment for something you can correct — address, phone, customs, parcel, or a stale rate | 422 |
| The carrier is temporarily unavailable | 503 — nothing to correct; retry later |
The request carries no idempotency key, but a repeat is recognized server-side:
sending the same purchase request again replays its outcome rather than buying a
second Label. For an ambiguous outcome (timeout, connection failure, or any
response you cannot attribute to success or failure), reissue the same request
within a bounded budget, or read the Order. A request that is not the same
purchase is refused with 409 instead of starting a competing one — correct it
rather than looping. See
Buy a Label for the exact conditions and
Retries and Ambiguous Outcomes.
Binary download failures
GET/api/v1/labels/{labelId}/download
| Situation | Status |
|---|---|
| Label file ready | 200 (binary body — application/pdf or application/zpl) |
| File still being generated | 202 — pending or still generating; no polling interval is defined |
Invalid request (e.g. unsupported format) | 400 |
| Missing or no-longer-usable bearer token | 401 |
| Label not found, or the requested format was never generated for it | 404 |
| Label generation conflicts with its current state | 409 |
| Label generation failed, or an internal error occurred | 500 |
| The carrier is temporarily unavailable | 503 — nothing to correct; retry later |
These failures do not use the normal {success, data, errors} JSON envelope.
They return a flat error object instead — code, description, category,
metadata. The one exception is 401, which is raised before the operation
runs and does use the envelope. Inspect the HTTP status and Content-Type
header before treating the body as either JSON or a label file. See
Download a Label for working examples.
Cancellation
DELETE/api/v1/labels/{labelId}
| Situation | Status |
|---|---|
| Label does not exist for your account | 404 |
| Invalid request | 400 |
| The Label cannot be cancelled as it stands — its Shipment has no tracking code to cancel against | 422 |
The documented result is data.isSuccess. Do not infer provider action, Label
state, refund status, or repeat-request safety from that boolean.
Recover safely
Treat file download failures separately from normal JSON handling. After an ambiguous cancellation response, do not blindly repeat the request; use your application's operational process without treating it as an API recovery flow.
See Order-to-Label Workflow and Retries and Ambiguous Outcomes.