Shipping Error Labels

What Are Error Labels?

Error labels is a practical exception management tool designed to help warehouse teams immediately understand when and why a shipping label fails to generate. Instead of showing a blank or generic error in the packing station, a printable label is generated that clearly says “ERROR LABEL” and includes a message explaining the issue (e.g., missing shipping method, invalid zip code, etc.). Here’s an example of what an error with a label might look like in JSON format:

{
  "error": "missing shipping_method",
  "details": {
    "label": "<base64-encoded ZPL string>"
  }
}

This label contains the same error message as human-readable text, create timestamp, site id, trace id and pending shipment lookup id (if pending shipments is enabled) encoded in ZPL format (used by label printers).

Why Use Error Labels?

Error labels offer several benefits, particularly in logistics and fulfillment scenarios:

• Real-time visibility at the packing station: Staff see instantly what went wrong without needing to debug logs.
• Operational continuity: Allows packers to print a temporary error label and continue working, while the issue is fixed in the Transport Administration system (TA).
• Better coordination: Teams can clearly mark problematic parcels and resolve errors directly where they happen.

Example

When error lables are enabled the error response when booking parcels will contain an extra field with base64 encoded ZPL format error label.

Error response including label:

HTTP/1.1 400 Bad Request
Date: Fri, 09 May 2025 06:38:07 GMT
Content-Type: application/json
Content-Length: 922
Connection: close
Vary: Accept-Encoding
x-trace-id: S20250509063806V234X2PDWTHYZ0Z1

{
  "error": "rpc error: code = InvalidArgument desc = invalid request: address_to.address.postal_code is required",
  "trace_id": "S20250509063806V234X2PDWTHYZ0Z1",
  "details": {
    "label": "XlhBIF5MSDAsMCBeQUEsMjAsMjAgXkZPMjAsNTAgXkZERXJyb3I6IHJwYyBlcnJvcjogY29kZSA9XkZTIF5BQSwyMCwyMCBeRk8yMCw4MCBeRkRJbnZhbGlkQXJndW1lbnQgZGVzYyA9IGludmFsaWReRlMgXkFBLDIwLDIwIF5GTzIwLDExMCBeRkRyZXF1ZXN0Ol5GUyBeQUEsMjAsMjAgXkZPMjAsMTQwIF5GRGFkZHJlc3NfdG8uYWRkcmVzcy5wb3N0YWxfY29kZV5GUyBeQUEsMjAsMjAgXkZPMjAsMTcwIF5GRGlzIHJlcXVpcmVkXkZTIF5BQSwyMCwyMCBeRk8yMCwyMzAgXkZEUGVuZGluZyBzaGlwbWVudCBJRDogZDNhOTI5XkZTIF5BQSwyMCwyMCBeRk8yMCwyOTAgXkZEQ3JlYXRlZCBhdDogMjAyNS0wNS0wOVQwNjozODowN1peRlMgXkFBLDIwLDIwIF5GTzIwLDM1MCBeRkRTaXRlIElEOiAxMTc1NmU0YTk4YzY0ZmE5YTljNWQ2Ml5GUyBeQUEsMjAsMjAgXkZPMjAsMzgwIF5GRDdmZDg4YTIzNl5GUyBeQUEsMjAsMjAgXkZPMjAsNDQwIF5GRFRyYWNlIElEOl5GUyBeQUEsMjAsMjAgXkZPMjAsNDcwIF5GRFMyMDI1MDUwOTA2MzgwNlYyMzRYMlBEV1RIWVowWjFeRlMgXlha"
  }
}

The decoding error label contains ZPL:

^XA ^LH0,0 ^AA,20,20 ^FO20,50 ^FDError: rpc error: code =^FS ^AA,20,20 ^FO20,80 ^FDInvalidArgument desc = invalid^FS ^AA,20,20 ^FO20,110 ^FDrequest:^FS ^AA,20,20 ^FO20,140 ^FDaddress_to.address.postal_code^FS ^AA,20,20 ^FO20,170 ^FDis required^FS ^AA,20,20 ^FO20,230 ^FDPending shipment ID: d3a929^FS ^AA,20,20 ^FO20,290 ^FDCreated at: 2025-05-09T06:38:07Z^FS ^AA,20,20 ^FO20,350 ^FDSite ID: 11756e4a98c64fa9a9c5d62^FS ^AA,20,20 ^FO20,380 ^FD7fd88a236^FS ^AA,20,20 ^FO20,440 ^FDTrace ID:^FS ^AA,20,20 ^FO20,470 ^FDS20250509063806V234X2PDWTHYZ0Z1^FS ^XZ

Which will be printed as:

How to Enable Error Labels

Contact Ingrid Customer Support.