Most UPS errors come down to a handful of causes: a field that is too long, a special character UPS can't read, a state or province code in the wrong format, or account credentials that don't match what UPS expects. This guide lists the UPS error messages merchants see most often when creating labels in the ShippyPro shipping platform, with the cause and the fix for each one.
Errors are grouped by type (account, address, customs, rates, labels, pickups and API), so you can jump to the section that matches the message on your screen. If you haven't connected UPS yet, start with the UPS integration page and the full list of ShippyPro integrations.
UPS does not support the full Unicode character set. It automatically converts special characters into "safe" ones, so symbols, non-Latin characters and accented letters (ä, ö, ü, è, ì, ò, à) can appear corrupted or distorted on the printed shipping label.
Every UPS order that fails lands in the Errors section of your dashboard. Here's how to find the cause and correct it:
From your ShippyPro dashboard, go to Orders > Errors.
Click How to Fix? to see detailed instructions for that error.
Use the wrench icon to edit the shipment details.
One quick note before the error list: ShippyPro does not support the UPS World Ease service.
These UPS errors usually mean the account number, password or access key connected to ShippyPro doesn't match what UPS has on file.
Your contract rates haven't been synchronized yet.
The Account Number may be wrong or suspended. 👉 Check with your UPS contact.
Get in touch with your UPS representative to resolve this one.
This usually happens when the account number used as Shipper hasn't been added and authenticated in the customer's My UPS profile on ups.com, under Billing and Account Numbers.
Important: only the customer can run this check, by logging in to ups.com with the same credentials used to create the application that generates the OAuth 2.0 tokens (set up through the UPS Developer Portal).
To fix it:
There are two common causes:
Your XML access key isn't valid.
UPS error code 250002 appears when the UPS account password no longer matches the one used when the account was set up (because it was reset or changed). If updating it doesn't help, delete the connection and create a new one from the Carriers section.
📌 Note: tracking links and updates for previous orders will no longer be available after you delete the connection.
The UPS password saved in ShippyPro no longer matches your UPS account (it was reset or changed), and too many attempts were made with the wrong password. To fix it:
This message comes directly from the UPS server. 👉 Contact your UPS representative or UPS customer service to find out why your account is blocked.
UPS doesn't recognise the account number used for billing.
Create a brand new UPSv2 connection from the Carriers page.
To bill a third-party account number, use the carrier options exw_third_party_zipcode and exw_third_party_country to enter the payer's details. Without these parameters, the recipient's data is used by default.
There are two possible fixes depending on your setup:
UPS is strict about field lengths and formats. Most address errors come from text over the 35-character limit, a postal code in the wrong format, or a state or province written out in full.
The Name and Company fields can't be longer than 35 characters on UPS labels.
The postal code must have exactly 5 digits, with no special characters such as "-" or "/".
Use the province abbreviation in the Recipient State field. Writing the full name causes the error.
Check the Sender State/Province field and use the abbreviation for Italian provinces. For some countries (such as the Netherlands) this field can be left empty for UPS: remove any data from it and process the shipment again.
Enter the province abbreviation or ISO code in the Recipient State/Province field (e.g. Barcelona > B, Alicante > A). If that doesn't work, reprocess the order with the field left empty.
The State/Province field can't be longer than 5 characters. If it is, replace it with the correct province abbreviation and process the order again.
Shipping to Ireland (128100)? Make sure the Province field contains the correct ISO code for the destination country. For Irish shipments, enter "IE" in the State/Province field and process the shipment again. If the error continues, replace the postal code with "IED".
UPS doesn't recognise "PR" as a state abbreviation for Puerto Rico. Set the country to Puerto Rico instead of USA and leave the state field empty.
UPS runs a validation check and returns this error when the Address, City, Postal Code or State doesn't match the real address. Review all four fields.
For shipments to the United States, a valid postal code has 5 digits and no letters.
Check the zip code and the city.
The Address 2 field of the sender or recipient is too long. The maximum is 35 characters.
If you see this error with UPSv2, check that the sender address:
📌 Note: if you activated Use your company info as the fixed shipper in the carrier connection modal (Carriers > UPSv2 > Edit), the address UPS checks is the one in My Profile > Sender Info. The Address field must stay within the character limit, and the House No. field should only contain the house number.
📌 The combined limit for Address 1 and Address 2 is 35 characters, including spaces.
The UPS address field has a 35-character limit, and longer addresses trigger this error. 👉 Use the Address 2 field for extra details such as the doorbell name or apartment number.
Check whether Use your company info as default shipper is selected in your UPS connection. If the address doesn't match the one in My Profile > Sender Info, it can cause this error.
You can fix this in three ways:
"IsReturn": true to the Ship request.Remove the Use your company info as default shipper flag from Carriers > UPS > Edit and process the shipment again.
If you selected Fixed Shipper in the UPS connection module, the sender information comes directly from My Profile > Sender Info. Make sure the name and surname there don't exceed 35 characters.
The recipient phone number needs at least 10 alphanumeric characters. Also note:
See how ShippyPro connects UPS and your other carriers to your store in one platform. Book a demo with our team.
International UPS shipments add customs data, CN22 details and ETD documents to the mix. These are the errors that come up most often.
The Product Description field accepts up to 35 characters. Check that you haven't gone over the limit.
UPS limits the item description field to 35 characters. Check the length and shorten it if needed.
Remove all special characters from the description of the items being shipped, including the description in the CN22 document.
Delete all special characters from the addresses, the description of goods and the CN22 details.
The Country of Origin in the CN22 may be wrong. If you set up the Customs Info section under My Profile, check that each SKU involved has a valid Country of Origin.
Make sure the IOSS number is filled in correctly in My Profile > Sender Info. If the error continues, try removing the IOSS number and confirming the shipment again.
The maximum value supported for returns is 999 USD, converted to EUR where needed.
Disable the option Add freight charges to commercial invoice in your connection modal.
Since March 6, 2023, every package sent to, from or within Mexico needs a package-level description of the items shipped. 👉 Add it to your Mexican shipments.
The order goes over the maximum number of products UPS allows on a single shipment:
| Document type | Maximum products per UPS shipment |
|---|---|
| Package Packing List | 50 |
| Commercial Invoice, NAFTA, CO, EEI | 100 |
| Air Freight packing list | 1,000 |
In your connection modal, check the box Request UPS Commercial Invoice along with the label. If that doesn't work, ask your UPS sales representative whether you're authorized to generate forms externally.
This happens when more than one commercial invoice is uploaded for the same shipment. Make sure that:
👉 Remove the ETD documents from the Invoice Manager and correct the order.
If several documents of the same type end up attached to the same order, make sure Test Mode is disabled in the UPS connection: go to the Carriers section and click Edit next to the UPS logo.
For return shipments, the ETD document you uploaded may not be valid, because UPS doesn't accept some attachment types for returns. 👉 To fix it:
When you upload documents for an international UPS shipment, choose the right document type:
FormType = 99.UPS accepts the "Other" / "99" type because it matches the "07 - Customer Generated Forms" category its systems use.
The carrier option upsv2documents_only only works when the origin and destination countries are different. The origin can't be the USA, and the destination can't be CA, PR or MX.
UPS doesn't accept the incoterm used (DDP, EXW, etc.) for this shipment. Change it and try again.
This is a temporary issue on the UPS server. Try again later.
If the rates shown when you ship with UPS don't match the negotiated rates in your contract, try these steps:
For some countries (e.g. UAE, Slovenia), UPS limitations may prevent your negotiated or discounted rates from showing in ShippyPro. 👉 Double-check with your UPS contact.
If you can't see UPS rates and this error appears among the excluded carriers, open the UPS connection modal and remove the flag on View time in transit rates. If your tracking numbers are created in the format 1ZXXXXXXXXXXXXXXXX, you may also need to remove Test Mode from Carriers > Connections > Edit.
The full message reads "Failure: Unable to determine destination for Time in Transit Information. / Time in Transit information Unavailable. (111598)". Disable View Time in Transit from Carriers > Connection > UPS > Edit and create the label again.
Make sure View rates time in transit is flagged in the carrier connection.
The selected service can't physically deliver from the origin to the destination, or isn't available for that destination. For international shipments, also check that you added the CN22 details. Then verify that:
📌 Postcodes 6991, 6992 and 6993 can't be reached from Austria and are only served from Germany. Use the relevant German postcodes and set Germany as the destination country.
This is linked to the service code. Check that the selected service is available from the sender address.
Check the service type set in the carrier connection from Carriers > UPS > Edit. If you ship via API:
UPS SurePost isn't available in the standard label creator. You can only use it as a service through a Shipping API call.
Open your UPSv2 template from Carriers > Edit and choose the correct return service from the Return Service Type dropdown.
Managing a lot of returns? See how ShippyPro Easy Return works.
The shipment (usually a return) isn't compatible with the Signature required option selected in the UPSv2 connection on the Carriers page.
Go to Carriers > UPSv2 > Edit and pick the option you need from the Delivery Signature Option dropdown.
Cash on delivery isn't available for this shipment. Check with your UPS contact that cash on delivery is enabled on your contract. Note that cash on delivery may not be supported for shipments to Switzerland.
If this appears when you request UPS rates, check that the Total Value field isn't empty.
UPS doesn't accept multi-parcel shipments for the selected destination. Contact your account manager for details on this limitation.
There are two common causes:
You may also see this as "Missing package description".
For manual shipments:
For marketplace orders:
This error comes from the option selected in the Preferences section. 👉 Switch to a different option, such as order number.
This error relates to the Reference Number field (package reference number) sent to UPS. In ShippyPro, the order's TransactionID field maps directly to the ReferenceNumber parameter, so the error appears when that value breaks UPS rules. Check the TransactionID of the order in error and make sure it:
Check that you aren't using a service that doesn't return printable labels: UPS Return Service 1-Attempt (RS1), UPS Return Service 3-Attempt (RS3) and UPS Electronic Return Label (ERL) don't return labels.
UPS labels don't print that field. 👉 It's still sent to the carrier automatically when you fill in CarrierNote via API.
Both are UPS label settings that can't be changed. 👉 Don't worry: all the information is still sent correctly to the carrier.
You can't edit a shipment that has already been created. 👉 Create a new shipment from scratch.
This can happen when the shipment couldn't be delivered, the return process had already started and a new tracking number was assigned to the return. If you need a new shipment, create a manual shipment with the same details to avoid the error.
Check whether the order was first shipped with a different carrier and then modified. Carriers that don't support the VoidShipment function leave their tracking ID on the order, and the new carrier may reject it.
This can happen for several reasons. Work through these steps in order:
To check the link:
Not every UPS service sends tracking notifications. You can tell which ones do by their NotificationCode:
| NotificationCode | Notification | Applies to |
|---|---|---|
| 2 | Return notification or label creation | Return shipments only. Not applicable to GFP (Ground Freight Pricing) |
| 5 | In-Transit notification | Return shipments only |
| 6 | Ship Notification | Forward shipments only |
| 7 | Exception Notification | Not applicable to GFP |
| 8 | Delivery Notification | All shipments |
Want branded tracking updates across all your carriers? Take a look at ShippyPro Track & Trace.
If you selected a Pickup Point ID through the carrier option, you also need to select a Pickup Point Mode (Hold for Pickup or Access Point Delivery), and the other way round.
If you ship via API with the Pickup Point Mode carrier option, enter the correct code in the "value" parameter:
When shipping through the API, select the Pickup Point Mode carrier option and set the value to 02.
Fill in both the phone number and the email address in the to_address fields.
If this appears when booking a pickup:
If you see this when booking a pickup, the service you're using doesn't support pickups from that origin. 👉 Check this with UPS.
UPS needs a minimum gap between the time the package is ready for pickup (ready time) and the closing time for that location. If your closing time is too close to your ready time, the booking fails. To fix it:
Some UPS errors have nothing to do with your data. They come from the UPS servers and usually clear up on their own.
This is a temporary UPS server issue. Try confirming the order again later.
If this appears while comparing rates, refresh the page. UPS may be handling a high volume of requests and can't process them all at once. 👉 Try again later.
The UPS system that handles tracking requests and package updates is having an issue, so the carrier can't reach its server and the shipment can't be processed. 👉 Wait a while, then reprocess the shipment to give UPS time to fix the problem.
If you connect your store or ERP through the ShippyPro API, these are the UPS API errors to watch for.
The CarrierName field in the API call isn't filled in correctly. With the UPSv2 modal, it must read:
"CarrierName": "UPSv2"Make sure the carrier's Packaging Type Quantity option is set correctly in the Ship call.
To send the value 01 (UPS Letter / Envelope), include "package": 1 in the Ship call. Without it, ShippyPro sends the value 2 by default. Check the payload your ERP sends, or review the API logs on the API page of ShippyPro.
This happens when shipping dangerous goods and the "Package identifier" option is missing or invalid. Ask UPS for the identifier to use for the shipment.
📌 Note: the field is 5 digits long.
Include the carrier option upsv2hazardous_materials set to 1 in the API call. On its own, though, this isn't enough: UPS also needs several fields describing the goods, and without them the shipment returns an error.
| Carrier option | What it contains |
|---|---|
upsv2hazmat_regulation_set |
The applicable regulation (e.g. ADR, IATA, CFR, TDG) |
upsv2hazmat_transportation_mode |
The transportation mode |
upsv2hazmat_commodity_regulated_level_code |
The regulation level (e.g. FR, LQ, EQ, LR) |
upsv2hazmat_proper_shipping_name |
The official name of the hazardous material |
upsv2hazmat_id_number |
The UN/NA/ID number of the product |
upsv2hazmat_class_division_number |
The hazard class/division |
upsv2hazmat_packaging_type and upsv2hazmat_packaging_type_quantity |
The type and quantity of packaging |
upsv2hazmat_quantity and upsv2hazmat_uom |
The quantity of goods and the unit of measure |
upsv2hazmat_emergency_contact and upsv2hazmat_emergency_phone |
An emergency contact name and phone number |
Most UPS errors come from field limits and formats: names, addresses and descriptions over 35 characters, postal codes in the wrong format, and full state names instead of abbreviations. Account issues, such as an account number not linked to your ups.com profile or an outdated password, are the next most common cause.
Go to Orders > Errors in ShippyPro, correct the data, then use Actions > Fix orders in error in bulk to retry them together. For a single order, click Fix Order.
UPS doesn't support the full Unicode character set and converts special characters into "safe" ones. Symbols, non-Latin characters and accented letters such as è or ü can appear distorted on the label, so it's best to avoid them in addresses and item descriptions.
Book a demo and see how ShippyPro handles labels, rates and tracking for your UPS shipments.