Errors can happen for various reasons. In this article, we'll cover over the most common error messages, what they mean and how to resolve them!
Carrier Specific Errors:
"Unable to Validate Address"
When you see the error "Unable to Validate Address", you can troubleshoot the address directly on the USPS website. If the address is a U.S. address you can use this link: https://tools.usps.com/go/ZipLookupAction_input
Some of the most common causes for an invalid address are:
- "Name" field only has one name (must have at least two; a first and last name, or a two part company name)
- Missing suite/apartment/unit number
- Missing house/building number or incomplete street name
- Use of non-English characters like "ñ" or "街頭"
- Suite/apartment/unit number/etc on the wrong line, should be on ‘Street 2’, not ‘Street 1’
- The street name is misspelled or missing information
- Ex: ‘Woodburt’ instead of ‘Woodburn’
- Ex: 'Cavanaugh' instead of 'Cavanaugh St.'
- Street name and suffix all one word, should be two words
- Ex: ‘Hill St’ instead of ‘HillSt’
- Too much information is included in street address
- Ex: ‘8550 NW 51st Street Lauderhill’ instead of ‘8550 NW 51st Street’
- Company name included in ‘Street 1’
- Ex: ‘Company Name LLC 2269 Chestnut St’ instead of ‘2269 Chestnut St’
- Using symbols instead of writing out words
- Ex: ‘Lewis & Clark Rd’ instead of ‘Lewis and Clark Rd’
- Abbreviations used when they shouldn’t be
- Ex: ‘Co Rd 704’ instead of ‘Country Road 704’
- Ex: ‘ACR 425’ instead of ‘Country Road A 425’
- Missing the 4-digit zip code extension
- Ex: ‘10009’ instead of ‘10009-4153’
If you're still not seeing what the error is, try Googling the address, and compare how the address appears in Google Maps to how it looks in Shippo. Ultimately, if you cannot determine the correct address, you may need to contact your customer to verify the address with them.
Military addresses can also be tricky. If you’re having trouble validating a military address, you can find the correct formats for APO, FPO, and DPO addresses here. If the format is correct and the customer confirms the address is valid, the issue might be with the address validation system. We use USPS' validation tool and their database is usually a month out of date. If this is the case, please contact us.
"The sender address must contain a first and last name, or a company name must be added"
- This error message refers to the sender/return address in Shippo. USPS will return an error if the sender or recipient information is incomplete.
- On international labels, the name for both the sender and the recipient address must follow a strict format of a "first name" and a "last name" and both must have more than one character. These do not have to be your actual first and last name but can be your business name. For example, instead of just "Shippo" in the first name field, "Shippo Inc." could be used to complete both fields.
"Invalid value for From First Name. When specified, a minimum of 2 characters must be supplied."
- USPS has strict rules around how the "name" is shown on international labels. For international labels, please ensure the "name" field of both your Sender AND Return address to a valid two-word value with at least two characters each, like a "first" and "last" name. This can be a variation of your company name but will need to be two words.
- For example, if the name was listed as "Shippo", it would need to be changed to something like "Go Shippo" so that it had two "words" and each word had two characters.
"UPS label service error: Severity: Hard, code: 120206: detail: Missing or invalid ship to state province code"
- UPS only requires a "State" field for shipments going to the U.S, Canada, Ireland and Australia. For shipments going to all other countries, leave the "State" field blank.
"UPS label service error: Severity: Hard, code: 120100: detail: Missing or invalid shipper number"
This error should only return for personal UPS accounts. If you are using Shippo's Master UPS account, please contact us.
You may have received this error for a number of reasons.
- The most common is incorrect UPS credentials being entered in Shippo. First double check your UPS credentials on the Carriers page in Shippo and make sure they're correct. Once they're correct that error will be resolved. Some fields cannot be edited, so you may need to setup a new UPS connection on the Carriers page by clicking on the Add Carrier Account button and entering the correct information again.
- If you are certain your credentials are correct, then it's possible that your shipper number (Account Number) was not added to your ups.com profile.
To verify you have the correct information in your ups.com profile:
- Log in to ups.com (Be sure to use the same User ID and Password that is in your Shipping API)
- Select Account Summary from the My UPS tab rollover menu.
- Verify that your account is listed; if not, select the Add a UPS Account link
- Follow the instructions to add the account
"UPS: UPS label service error: Severity: Hard, code: 120121: detail: The Shippers shipper number cannot be used for the shipment"
- This error should only return for personal UPS accounts. If you are using Shippo's Master UPS account, please contact us.. This error is returned from UPS and indicates an issue with your UPS account and not with the information you're entering in Shippo. This can be related to your account being deactivated or blocked for some reason with UPS which prevents the purchase of labels for that UPS account.
- Please contact UPS to resolve: https://www.ups.com/content/us/en/contact
"UPS label service error: Severity: Hard, code: 120109: detail: Missing or invalid Shipper phone number"
- Phone numbers are required for the recipient, sender, and return addresses for all international shipments and for domestic shipments with some carriers. This error means the "shipper" phone number was missing. That means your own phone number. Please visit the Shippo Addresses Page to add a phone number for both your sender and return addresses.
UPS: RatedShipmentWarning: Your invoice may vary from the displayed reference rates
- To see negotiated rates in Shippo, you will need to connect UPS using a recent UPS invoice. For a full walkthrough please see: Connect Your UPS account
- If you have your account set up to be billed weekly or monthly based on the number of shipments you do (for example, if you ship more than a certain number of packages in a particular month) then your total bill for the month may be adjusted down - the rates you see in Shippo may not exactly match what you see from UPS.
"Default Payment Method" (Canada Post)
This error indicates that Canada Post thinks that there is no valid default credit card saved for your account.
There are three types of Canada Post accounts: standard, contract/credit card, and contract/account billing.
This error can occur if:
- You have a billing account but you've selected “credit card” as your Canada Post payment method.
- You're a credit card customer, but the card you have on file with Canada Post is invalid or expired.
- You have a standard account, not a contract account, but you've put a value into the “contract ID” field, when connecting Canada Post to Shippo.
- You have a contract with Canada Post but have not entered your contract information.
Please double check your Canada Post account information in order to correct this issue.
"Failed to load PDF"
- If you see a Failed to load PDF error when you're trying to download and print your label, it generally means that there was a timeout from the Carrier when the label was produced. We have instituted a retry sequence when our system detects these types of timeouts, and we will reattempt to retrieve the label from the carrier several times before it's a failed purchased. This retry logic makes this failed to load PDF error far less common.
- If you do see a Failed to load PDF error instead of your label opening, please request a refund and try your label purchase again.
FedEx Ground Rates
If you’re not seeing FedEx Ground rates, it may be because you’ve indicated that a shipment is going to a residential address.
- FedEx Ground and FedEx Home Delivery are actually the same service, except Ground is for commercial recipient addresses and Home Delivery is for residential recipient addresses. On Shippo, “residential” is checked as default.
- If you know the package is going to a commercial address, uncheck the “residential recipient” box to see FedEx Ground rates.
FedEx SmartPost Rates
The most common reason FedEx SmartPost rates aren't displaying is due to an incorrect "FedEx Smartpost Hub ID."
Keep in mind the "Smartpost Hub ID" is not necessarily just the closest Hub to your address, but is assigned specifically to each FedEx account. You need to check with your FedEx representative in order to confirm your Hub ID. You'll find the full list of these IDs on the FedEx website: http://www.fedex.com/us/smart-post/network.html
FedEx SmartPost also has minimum dimensions. Minimum dimensions of 6 x 4 x 1 in must be entered to see SmartPost rates.
"2209: ERROR: Inactive customer account"
- This message comes directly from FedEx and indicates a problem with your FedEx account. Shippo cannot resolve this error. You will need to reach out to FedEx to resolve the issue and re-activate your account. FedEx customer service is located at: https://www.fedex.com/en-ca/contact-us.html
"FedEx: ERROR: RequestedShipment Recipient contact - phoneNumber is required"
- Phone numbers are required for the recipient, sender, and return addresses for all international shipments and for domestic shipments with some carriers. This error means the recipient phone number was missing.
- If you don't have the recipient phone number, you can add your own phone number or a dummy number to the recipient address during label creation.
"Your account needs to have a valid payment method on file"
This error can indicate an issue with your payment method in Shippo.
- Head to Settings > Account > Billing in Shippo. If the payment method is correct, the issue may be with an unpaid invoice on the account.
Scroll to the "Invoices" section. If there is an unpaid invoice on the account, there will be a "Re-attempt Charge" link next to it. Click the link, and once the charge goes through, you should be all set to continue buying labels.
The most common reasons for this error are:
- Incorrect zip code
- Incomplete recipient address
- The package dimensions or weight exceed the restrictions set by the carriers you've activated
- A Flat Rate or Regional Rate package has been chosen but isn't available for this particular shipment
- The carrier's system is temporarily unavailable or not responding
- The carrier account is inactive in Shippo
Please check the dimensions and weight of your package, as well as the city/state/zip code combination, to resolve this issue. If all of that information is correct, or if you're getting that same error message for multiple different orders, please contact us.
When you see any of the following error messages when trying to get rates:
CanadaPost: AAA Authentication Failure
UPS (250002): Hard: Invalid Authentication Information
DHL: 'Invalid fieldlength in element 'PartnerID'
It means there is something incorrect in the account credentials you have entered for a given carrier. Please check Settings > Carriers to ensure the correct information was entered. If you still have issues, please don't hesitate to contact us.
"Ascii Codec Can't Encode Character"
This error indicates that there's a character or symbol in part of the label information that the carrier can't process. Typically this is something like ® or ™ in the lines of text you can add to a label under Settings > Labels in Shippo, but it could be in the address information as well.
"Missing or Invalid: ContentsType. Error encountered."
This error indicates that you have chosen an incorrect option from the "ContentsType" menu on the Customs page for an international shipment, most often "Return Merchandise." "Return merchandise" is not authorized for use to many countries, and with several service levels - using "Merchandise" instead will solve the problem.
If you are not seeing the specific error you are running into, or if you have any questions, please contact us!