How to Fix UPS Errors

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.

How to check and fix UPS errors in ShippyPro

Every UPS order that fails lands in the Errors section of your dashboard. Here's how to find the cause and correct it:

One quick note before the error list: ShippyPro does not support the UPS World Ease service.

UPS account, credentials and authentication errors

These UPS errors usually mean the account number, password or access key connected to ShippyPro doesn't match what UPS has on file.

"User Id and Shipper Number combination is not qualified to receive negotiated rates"

Your contract rates haven't been synchronized yet.

• Check that your credentials are correct.
• If they are, contact UPS and ask them to enable your rates via API.

"The shipper number cannot be used for the shipment"

The Account Number may be wrong or suspended. 👉 Check with your UPS contact.

"The Shipper's shipper number cannot be used for the shipment"

Get in touch with your UPS representative to resolve this one.

UPS error: "Missing or invalid shipper number"

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:

1. Log in to ups.com with the same User ID and Password used for the shipping API.
2. Go to My UPS > Billing and Account Numbers.
3. Check that the account number has been added and authenticated. If it hasn't, select Add a UPS Account and follow the steps.
4. Make sure any letters in the account number are uppercase (e.g. 1A2345), otherwise authentication won't work.

The Shipping API account number hasn't been added to your ups.com profile

There are two common causes:

1. Account Number not configured: the sender Account Number for the Shipping API isn't linked to your ups.com profile. Make sure it's correctly associated with your UPS account.
2. Credentials don't match the environment: you're using production credentials with Test Mode enabled, or the reverse. Use test credentials with Test Mode on, and production credentials with Test Mode off.

"Failure: Invalid Access License number (250003)"

Your XML access key isn't valid.

• Double-check the key.
• Make sure you have production access to the UPS address validation API.

UPS error 250002: "Invalid Authentication Information"

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 maximum number of user access attempts was exceeded (250006)"

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:

1. Check the password in the connection modal.
2. Contact UPS to unlock your account.
3. Fix the order.

"Failure: The UserId is currently locked out, please try again in 30 minutes. (250007)"

This message comes directly from the UPS server. 👉 Contact your UPS representative or UPS customer service to find out why your account is blocked.

"Invalid Bill-To type. (120444)"

UPS doesn't recognise the account number used for billing.

"Invalid/Missing Refresh Token"

Create a brand new UPSv2 connection from the Carriers page.

"UPS account number that was provided as the payment method is missing or invalid"

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.

"The country associated with Shipper's ShipperNumber must be the same as the shipment's Shipper's country" (120120)

There are two possible fixes depending on your setup:

• Enable or disable Use your company info as fixed shipper and Use your company info as fixed shipper for returns from Carriers > UPS > Edit.
• If the error persists, the customer code used for the connection may not allow a non-domestic sender address. Check this limitation with your carrier contact.

UPS address, name and character-limit errors

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.

"Name and company fields must be shorter than 35 characters"

The Name and Company fields can't be longer than 35 characters on UPS labels.

UPS postal code error: "Postal Code length must be 5 numbers"

The postal code must have exactly 5 digits, with no special characters such as "-" or "/".

"Province must be in the form of an abbreviation"

Use the province abbreviation in the Recipient State field. Writing the full name causes the error.

"Missing or invalid ship from StateProvinceCode (120306)"

• Disable Enable Paperless if it's active.
• Select Use your company info as fixed shipper from Carriers > UPS > Edit.
• Update the shipment by clicking Edit and then Confirm in the Shipping Labels menu.

"Missing or invalid ship from state province code"

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.

"Missing or invalid ship to state province code"

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.

"Invalid sold to state province code. Valid length is 0 to 5 alphanumeric"

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".

"PR is not a valid state for the specified shipment"

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 address validation error: "Failure: Address Validation Error on ShipTo address (120802)"

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.

"Invalid Destination (111542)"

Check the zip code and the city.

"Invalid ShipFrom AddressLine2" and "Failure: Invalid ShipTo AddressLine2 (120203)"

The Address 2 field of the sender or recipient is too long. The maximum is 35 characters.

"Missing or invalid ship from address line 1"

If you see this error with UPSv2, check that the sender address:

• is valid and can be geolocated;
• stays within 35 characters including spaces (35 for Address 1 and 35 for Address 2).

📌 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.

"Missing or invalid ship to address line 1"

• Shorten Address 1 to 35 characters or fewer, including spaces.
• Remove the Address 2 field to avoid mismatches with the courier's street map. UPS merges Address 1 and Address 2, so only use Address 2 when the main address won't fit in Address 1.

📌 The combined limit for Address 1 and Address 2 is 35 characters, including spaces.

"Missing or invalid shipper address line 1"

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.

"Missing or invalid ship from address"

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.

"Failure: The ShipFrom country must be the same as the Shipper country (120317)"

You can fix this in three ways:

• Go to Carriers > Connection > UPS > Edit and enable Use your company info as fixed shipper.
• Mark the order as a return label by clicking the return toggle before you create it.
• If you use the API, add "IsReturn": true to the Ship request.

"Invalid Unit of Measurement for the given country"

Remove the Use your company info as default shipper flag from Carriers > UPS > Edit and process the shipment again.

Name and company name errors

• "Missing or invalid ship from company name": check that the Company Name field in your order is filled in correctly.
• "Missing or invalid ship to company name": correct the Recipient Name field so it has 35 characters or fewer.
• "Missing or invalid Shipper AttentionName": the Sender Name field allows up to 35 characters, spaces included.

"ShipTo PhoneNumber must be at least 10 alphanumeric characters"

The recipient phone number needs at least 10 alphanumeric characters. Also note:

• numbers made up only of zeros (e.g. 0000000000) or starting with 0 aren't valid;
• the number must follow the phone format of the destination country.

Spend less time fixing UPS labels

See how ShippyPro connects UPS and your other carriers to your store in one platform. Book a demo with our team.

UPS customs, international and commercial invoice errors

International UPS shipments add customs data, CN22 details and ETD documents to the mix. These are the errors that come up most often.

"Invalid product description for product number 1. Product description should be present at least once. Valid range is 0 to 35 alphanumeric"

The Product Description field accepts up to 35 characters. Check that you haven't gone over the limit.

"Failure: Invalid merchandise description of package (120623)"

UPS limits the item description field to 35 characters. Check the length and shorten it if needed.

UPS error 10002: "To be reprocessed: Failure: The request is well formed but the request is not valid"

Remove all special characters from the description of the items being shipped, including the description in the CN22 document.

"json_encode error: Malformed UTF-8 characters, possibly incorrectly encoded"

Delete all special characters from the addresses, the description of goods and the CN22 details.

"Invalid or missing product origin country code for product number 1"

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.

"Missing or Invalid Vendor Collection ID Number"

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 declared amount was exceeded. Maximum value per package: 856 EUR. (121025)"

The maximum value supported for returns is 999 USD, converted to EUR where needed.

"Invalid freight charges monetary value. Valid length is 0 to 15 numeric and can hold up to 2 decimal places"

Disable the option Add freight charges to commercial invoice in your connection modal.

Why are my Mexican shipments going in error?

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.

"Invalid number of products"

The order goes over the maximum number of products UPS allows on a single shipment:

"There was an error while uploading the file. Please try again later. Your UPS Account number is not authorized for user generated forms functionality"

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.

"A shipment can only contain one Commercial Invoice"

This happens when more than one commercial invoice is uploaded for the same shipment. Make sure that:

• you don't have ETD documents uploaded while Generate Commercial Invoice is enabled in the carrier connection (the two can't be used together);
• you didn't upload the documents twice via the API.

👉 Remove the ETD documents from the Invoice Manager and correct the order.

"ETD Documents Not Correctly Attached to 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.

"Invalid or missing international forms form type for shipment with return service. Valid value is 01 or 05"

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:

• Remove the ETD from the Invoice Manager section.
• Enable the right option in your UPS connection (Carriers section) so the UPS commercial invoice is generated correctly.
• If you upload your own ETD document, pick the correct document type. Uploaded as "Invoice" (Type 0), ShippyPro sends FormType 01 to UPS, but UPS requires FormType 07 / Other (Customer Generated Forms) for custom documents. Upload it as Type "99" / "Other" instead, and ShippyPro will convert it to FormType 07 in the request to UPS.

My documents aren't being sent correctly to UPS for international shipments

When you upload documents for an international UPS shipment, choose the right document type:

• On the ShippyPro platform, select Other from the dropdown menu.
• Via API, set FormType = 99.

UPS accepts the "Other" / "99" type because it matches the "07 - Customer Generated Forms" category its systems use.

"Shipment DocumentsOnly is invalid with the shipment's origin/destination pair"

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.

"The requested billing option is unavailable between the selected locations"

UPS doesn't accept the incoterm used (DDP, EXW, etc.) for this shipment. Change it and try again.

UPS rates, services and transit time errors

"Negotiated rates are unavailable at this time"

This is a temporary issue on the UPS server. Try again later.

What can I do if my UPS rates are not correct?

If the rates shown when you ship with UPS don't match the negotiated rates in your contract, try these steps:

1. If you see "User Id and Shipper Number combination is not qualified to receive negotiated rates", ask UPS to upload your rates via API.
2. Check whether Show tariffs with no VAT is enabled in My Profile > Preferences.
3. Try disabling View Time in Transit rates and enabling Use your company as Fixed shipper from Carriers > Edit.
4. If Test Mode is on but you're using production credentials, disable it from Carriers > UPS > Edit.

Why do I get wrong rates for some countries?

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.

"No matching rate and transit times available (111562)"

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.

UPS error 111598: "Unable to determine destination for Time in Transit Information"

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.

Why is the transit time wrong when I get carrier rates?

Make sure View rates time in transit is flagged in the carrier connection.

"The requested service is unavailable between the selected locations"

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:

• the shipping service in the carrier connection modal (Carriers > UPSv2 > Edit) is correct. To see every service UPS returns for that route, select All Services as the Service Type;
• the zip code is accurate and matches the city;
• the zip code has no extra letters or spaces;
• the sender's postal code is correct.

📌 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.

"The requested service is invalid for the shipment origin"

This is linked to the service code. Check that the selected service is available from the sender address.

"Missing or invalid service code"

Check the service type set in the carrier connection from Carriers > UPS > Edit. If you ship via API:

• don't select All Services;
• set the specific service in both the connection and the API call.

Why can't I see UPS SurePost when creating shipments?

UPS SurePost isn't available in the standard label creator. You can only use it as a service through a Shipping API call.

"Invalid return service. Check the selected service in carrier configuration"

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 Delivery Confirmation option cannot be combined with the Return Services option"

The shipment (usually a return) isn't compatible with the Signature required option selected in the UPSv2 connection on the Carriers page.

How can I set a signature requirement for all UPS shipments?

Go to Carriers > UPSv2 > Edit and pick the option you need from the Delivery Signature Option dropdown.

"The accessory is invalid with the billing option"

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.

"Invalid Shipment Contents Value"

If this appears when you request UPS rates, check that the Total Value field isn't empty.

"Only one package is allowed for this movement"

UPS doesn't accept multi-parcel shipments for the selected destination. Contact your account manager for details on this limitation.

UPS shipping label, printing and description errors

"Printing could not be managed for the selected orders, please try again with fewer orders"

There are two common causes:

• ZPL labels with a UPS commercial invoice: the invoice is always issued as a PDF, so the two formats don't match. 👉 Change the label type setting to PDF.
• Cash on delivery (COD): UPS always returns a GIF label when COD is selected, which ShippyPro then converts to PDF. For this reason COD + ZPL isn't supported. 👉 Use PDF.

UPS API missing package description error: "Shipment Description is required for this shipment"

You may also see this as "Missing package description".

For manual shipments:

• If you chose to print "Marketplace Order number" under My Profile > Preferences > Content description printed on the labels, fill in the Order Number field when creating the shipment (or the TransactionID field if you ship via API).
• If the error persists, change that option to "ShippyPro order number" or "Order Description".

For marketplace orders:

• Enter ONLY the transaction ID in the (Items) Description field.
• If that isn't enough, select Marketplace order number under My Profile > Preferences > Content description printed on labels.

"Shipment Description cannot exceed the length of 50 characters"

This error comes from the option selected in the Preferences section. 👉 Switch to a different option, such as order number.

"Invalid Package Reference Value"

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:

• is no longer than 35 characters;
• has no special characters (e.g. /, -, @, accented characters).

I created a UPS shipment but only see the tracking number, not the label

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.

Why can't I see my UPS notes on the label?

UPS labels don't print that field. 👉 It's still sent to the carrier automatically when you fill in CarrierNote via API.

Why are Address 1 and Address 2 inverted, or sender Address 2 missing, on the label?

Both are UPS label settings that can't be changed. 👉 Don't worry: all the information is still sent correctly to the carrier.

"International Shipments cannot be voided at the package level"

You can't edit a shipment that has already been created. 👉 Create a new shipment from scratch.

"The Shipment was not voided"

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.

"Invalid or Missing ShipmentIdentificationNumber"

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.

UPS notification, pickup point and pickup booking errors

"Missing or invalid Notification/NotificationCode"

This can happen for several reasons. Work through these steps in order:

1. Deselect all active notifications in Carriers > UPS v2 > Edit > Email Notification (use Ctrl + click).
2. If they're already deselected, try selecting only:
   • QV Email Notification
   • QV Exception Notification
   • QV Delivery Notification Mail Innovation
3. If the error persists, your shipper number (Account Number) may not be linked to your UPS.com profile.

To check the link:

• Log in to ups.com with the same User ID and Password as the Shipping API.
• Go to My UPS > Account Summary.
• Check that your account is listed. If it isn't, click Add a UPS Account and follow the instructions.

Why don't I receive UPS tracking notifications?

Not every UPS service sends tracking notifications. You can tell which ones do by their NotificationCode:

Want branded tracking updates across all your carriers? Take a look at ShippyPro Track & Trace.

"Point_mode is required when point_id is set and vice versa"

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.

"Missing or invalid shipment indication type code"

If you ship via API with the Pickup Point Mode carrier option, enter the correct code in the "value" parameter:

• 01: Hold for Pickup
• 02: Access Point Delivery

"UPS Account is not authorized for Hold for Pickup at UPS Access Point Shipment"

When shipping through the API, select the Pickup Point Mode carrier option and set the value to 02.

"ADL notification code (012) and notification data (email or phone number) is required for UPS Access Point Delivery"

Fill in both the phone number and the email address in the to_address fields.

UPS error when you schedule a pickup: "SYSTEM.UNEXPECTED.ERROR GENERIC.ERROR"

If this appears when booking a pickup:

• try again a couple more times, or
• remove the Test Mode option from your connection modal.

"Invalid service designation"

If you see this when booking a pickup, the service you're using doesn't support pickups from that origin. 👉 Check this with UPS.

"Error while booking the pickup: Closing time is less than the minimum window after ready time"

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:

1. Move your ready time earlier: schedule the pickup for the morning or early afternoon instead of late afternoon.
2. Extend your closing time: if you can, give a later closing time to widen the window.
3. Check local depot hours: make sure your times fall within your local UPS depot's opening hours.
4. Check time zones: UPS uses local time for the closing time (PickupAfternoonMaxtime), while the ready time (PickupTime) should be sent as a GMT timestamp.

Temporary UPS server errors

Some UPS errors have nothing to do with your data. They come from the UPS servers and usually clear up on their own.

"Failure of Web Server bridge"

This is a temporary UPS server issue. Try confirming the order again later.

• Click Fix Order to retry, or
• use Actions > Fix orders in error in bulk if several orders are affected.

"Client error: POST https://onlinetools.ups.com/ups.app/xml/Rate resulted in a 429 Too Many Requests"

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.

"RSS web service currently unavailable"

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.

UPS API and dangerous goods errors

If you connect your store or ERP through the ShippyPro API, these are the UPS API errors to watch for.

"Invalid Carrier"

The CarrierName field in the API call isn't filled in correctly. With the UPSv2 modal, it must read:

"Number of Packages must be specified"

Make sure the carrier's Packaging Type Quantity option is set correctly in the Ship call.

We send a "letter" type via the API, but UPS processes it as a parcel

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.

"Missing or invalid PackageIdentifier"

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.

How do I use the UPS Dangerous Goods option? ("Shipper is not eligible to ship Hazardous Material / International Dangerous Goods")

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.

Ship with UPS and all your carriers from one place

Book a demo and see how ShippyPro handles labels, rates and tracking for your UPS shipments.