Error messages can be confusing and frustrating. We've compiled this list of common error messages, what they mean, and how to resolve them so you can get back to business as usual.
Many errors clear up once you clear your browser cache. Here's how:
Troubleshooting an API error? Check our API Guide.
Jump to the carrier your error relates to:
- USPS
- UPS
- Canada Post
- FedEx
- Other Errors
If you can't find your error message here, reach out to our support team.
USPS
"Unable to Validate Address"
Troubleshoot the address directly on the USPS website. For US addresses, use USPS Address Validation.
Common causes of an invalid address:
- The "Name" field has only one name (it needs at least two, like a first and last name, or a two-part company name).
- Missing suite, apartment, or unit number.
- Missing house/building number or an incomplete street name.
- Non-English characters, like "ñ" or "街頭."
- Suite/apartment/unit number on the wrong line. It belongs on "Street 2," not "Street 1."
- A misspelled or incomplete street name (for example, "Woodburt" instead of "Woodburn," or "Cavanaugh" instead of "Cavanaugh St.").
- Street name and suffix combined into one word instead of two (for example, "HillSt" instead of "Hill St").
- Too much information packed into the street address (for example, "8550 NW 51st Street Lauderhill" instead of "8550 NW 51st Street").
- A company name included in "Street 1" (for example, "Company Name LLC 2269 Chestnut St" instead of "2269 Chestnut St").
- Symbols used instead of words (for example, "Lewis & Clark Rd" instead of "Lewis and Clark Rd").
- Abbreviations used where they shouldn't be (for example, "Co Rd 704" instead of "Country Road 704," or "ACR 425" instead of "Country Road A 425").
- Missing the 4-digit zip code extension (for example, "10009" instead of "10009-4153").
Still stuck? Try Googling the address and comparing how it appears in Google Maps to how it looks in Shippo. If you still can't pin down the correct address, you may need to check with your customer directly.
Military addresses can be tricky too. Find the correct formats for APO, FPO, and DPO addresses here. If the format looks right and your customer confirms the address, the issue might be with the address validation system itself. We use USPS's validation tool, and their database can run about a month behind. If that's the case, contact us.
"The sender address must contain a first and last name, or a company name must be added"
This error refers to the sender/return address in Shippo. USPS returns this error when sender or recipient information is incomplete.
On international labels, both the sender and recipient name must follow a strict "first name" and "last name" format, with more than one character in each. These don't have to be real first and last names. You can use your business name split across both fields, for example, "Shippo" in the first name field and "Inc." in the last name field.
"Couldn't buy label. Sender info missing email or phone. Sender email and phone number required for USPS."
This means your sender address is missing a phone number and/or email, both required by USPS. This information isn't printed on the label, it's used for the carrier's internal communications.
To fix it, click Edit Sender in the order details and make sure both a phone number and email are entered.
"Invalid value for From First Name. When specified, a minimum of 2 characters must be supplied."
USPS enforces strict rules for how names appear on international labels. Make sure the "name" field for both your sender and return address uses a valid two-word value, with at least two characters in each word, like a "first" and "last" name. This can be a variation of your company name, as long as it's two words.
For example, "Shippo" alone wouldn't work, but "Go Shippo" would, since it has two words with at least two characters each.
UPS
"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 US, Canada, Ireland, and Australia. For shipments to any other country, leave the "State" field blank.
"UPS label service error: Severity: Hard, code: 120100: detail: Missing or invalid shipper number"
This error should only appear for personal UPS accounts. If you're using Shippo's UPS Carrier Account, contact us.
A few reasons you might see this:
- Incorrect UPS credentials in Shippo. Double-check your UPS credentials on the Carriers page. Some fields can't be edited, so you may need to set up a new UPS connection instead: click Add Carrier Account on the Carriers page and re-enter your information.
-
Your shipper number (account number) wasn't added to your ups.com profile. To verify your ups.com profile:
- Log in to ups.com using the same User ID and password as your Shipping API.
- Select Account Summary from the My UPS tab rollover menu.
- Confirm your account is listed. If not, select Add a UPS Account.
- Follow the prompts 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 appear for personal UPS accounts. If you're using Shippo's UPS Carrier Account, contact us.
This error comes from UPS and points to an issue with your UPS account itself, not the information entered in Shippo. It often means your account has been deactivated or blocked by UPS, which prevents label purchases on that account.
Contact UPS directly to resolve it: UPS 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 on all international shipments, and on domestic shipments with some carriers. This error means your own ("shipper") phone number is missing. Visit the Shippo Addresses Page to add a phone number to both your sender and return addresses.
UPS: RatedShipmentWarning: Your invoice may vary from the displayed reference rates
To see your negotiated rates in Shippo, connect UPS using a recent UPS invoice. See Connect Your UPS Account for the full walkthrough.
If your UPS account is billed weekly or monthly based on shipment volume, your total monthly bill may get adjusted down, meaning the rates shown in Shippo might not exactly match what UPS ultimately charges.
Canada Post
"Default Payment Method"
This error means Canada Post doesn't see a valid default credit card on file for your account.
There are three types of Canada Post accounts: standard, contract/credit card, and contract/account billing. This error can come up if:
- You have a billing account, but selected "credit card" as your Canada Post payment method.
- You're a credit card customer, but the card on file with Canada Post is invalid or expired.
- You have a standard account, not a contract account, but entered a value in the "contract ID" field when connecting Canada Post to Shippo.
- You have a Canada Post contract, but haven't entered your contract information.
Double-check your Canada Post account information to correct this.
"Failed to load PDF"
This usually means the carrier timed out while producing the label. Shippo automatically retries a few times before marking the purchase as failed, which makes this error far less common than it used to be.
If you do see it instead of your label opening, request a refund and try the label purchase again.
"Rejected by SLM Monitor"
This is simply a time-out from Canada Post. Retrying the label purchase after a couple of minutes usually resolves it.
FedEx
FedEx Ground rates
If you're not seeing FedEx Ground rates, it may be because the shipment is marked as going to a residential address.
FedEx Ground and FedEx Home Delivery are the same service, just split by recipient type: Ground for commercial addresses, Home Delivery for residential ones. Shippo defaults to "residential" checked.
If you know the package is going to a commercial address, uncheck "residential recipient" to see FedEx Ground rates.
FedEx SmartPost rates
The most common reason SmartPost rates don't show up is an incorrect FedEx SmartPost Hub ID.
Your SmartPost Hub ID isn't necessarily your closest hub, it's assigned specifically to your FedEx account. Check with your FedEx representative to confirm your Hub ID, or find the full list on the FedEx website.
FedEx SmartPost also has minimum dimensions: you'll need to enter at least 6 x 4 x 1 in to see SmartPost rates.
"2209: ERROR: Inactive customer account"
This message comes directly from FedEx and points to a problem with your FedEx account. Shippo can't resolve this one. Contact FedEx directly to reactivate your account: FedEx Customer Service.
"FedEx: ERROR: RequestedShipment Recipient contact - phoneNumber is required"
Phone numbers are required for the recipient, sender, and return addresses on all international shipments, and on domestic shipments with some carriers. This error means the recipient phone number was missing.
If you don't have the recipient's phone number, add your own number or a placeholder number to the recipient address during label creation.
Other errors
"Your account needs to have a valid payment method on file"
This points to an issue with your payment method in Shippo. Go to Settings > Account > Billing.
If your payment method looks correct, the issue may be an unpaid invoice. Scroll to the "Invoices" section. If there's an unpaid invoice, click Re-attempt Charge next to it. Once the charge goes through, you'll be all set to continue buying labels.
"Label Purchase Failed: Missing Customs"
This error relates to missing or incorrect AES/ITN numbers on an international shipment. It typically means:
- Your shipment requires AES filing, but no exemption was selected.
- The AES/ITN number entered is invalid or missing.
To resolve it:
-
Check if your shipment qualifies for an exemption. Select the appropriate exemption code if one applies:
- NOEEI § 30.37a: If each type of goods in the shipment is valued at $2,500 or less and no export license is required.
- NOEEI § 30.36: Shipments to Canada, regardless of value, that don't require an export license.
- NOEEI § 30.37h: Authorized gift parcels or humanitarian donations to Cuba that don't require a Bureau of Industry and Security (BIS) export license.
- NOEEI § 30.37f: Exports of technology and software, as defined in 15 CFR part 772 of the Export Administration Regulations (EAR), that don't require an export license.
- Provide a valid AES/ITN number if an exemption doesn't apply. File through the AES system to obtain an ITN.
If the issue persists, double-check your entry for accuracy or consult export compliance guidelines.
"No Rates"
The most common reasons for this error:
- Incorrect zip code
- Incomplete recipient address
- Package dimensions or weight exceed the restrictions of your activated carriers
- A Flat Rate or Regional Rate package was selected but isn't available for that shipment
- The carrier's system is temporarily unavailable
- The carrier account is inactive in Shippo
Check your package's dimensions, weight, and city/state/zip code combination. If everything looks right, or you're seeing this error across multiple orders, contact us.
Authentication errors
If you see any of these:
- CanadaPost: AAA Authentication Failure
- UPS (250002): Hard: Invalid Authentication Information
- DHL: 'Invalid fieldlength in element 'PartnerID'
Something's off in the account credentials you entered for that carrier. Check Settings > Carriers to confirm the information's correct. Still stuck? Contact us.
"Ascii Codec Can't Encode Character"
This means a character or symbol somewhere in the label information can't be processed by the carrier. This is usually something like ® or ™ in custom label text under Settings > Labels, but it can also show up in address information.
"Missing or Invalid: ContentsType. Error encountered."
This means you've chosen an incorrect option from the "ContentsType" menu on the Customs page for an international shipment, most often "Return Merchandise." Many countries and service levels don't authorize "Return Merchandise." Switching to "Merchandise" usually solves it.
Not seeing your error here, or have more questions? Contact us.