About this guide

Some common issues that can be addressed by your organization along with potential resolutions are included in this guide. They are organized into two primary categories:

Response code errors for calls made to Shipium's APIs
Common issues with potential resolutions

For assistance resolving issues that extend beyond the ones in this guide, please reach out to Shipium Customer Support.

API response code errors

The Shipium APIs follow the API Response Codes standards unless otherwise specified.

Error responses generally fall into two groups based on the nature of the issue:

4XX. Client errors. Something in the nature of the request that was made prevents it from being completed. Examples include bad or missing data or lack of access to the data requested. These should usually be fixable by the caller.
5XX. Server errors. Something has gone wrong on the Shipium side of things, preventing us from responding to the request. Waiting and trying again may be successful, but the underlying reason does not appear to be related to details of the request made.

HTTP response code	Meaning	Contents
400 (Bad Request)	Missing required values or badly formatted input values	Details about the nature of the missing or incorrect values encountered
401 (Unauthorized)	You will receive a 401 most commonly if you attempt to either (1) access APIs without having first authenticated, or (2) utilize a service that your organization is not authorized to use (e.g., not paying for).	Make sure that you are following the pattern laid out in Authentication.
403 (Forbidden)	You will receive a 403 if you are authenticated but attempting to access data to which the authenticated credentials do not have access. For instance, if you authenticated as CompanyOne but tried to access a shipment that was part of CompanyTwo's account, you will receive a 403 response code.	Make sure that you are following the pattern laid out in Authentication.
404 (Not Found)	This is generally an issue with a bad ID (e.g., shipment ID or label ID) or a bad route.	Details about the ID that could not be found
429 (Too Many Requests)	You will only see a 429 if you have increased your call volume to a degree that it looks like a distributed denial-of-service (DDOS) attack. You should not expect to see this in practice other than maybe as a pass-through from a carrier while running in test mode.	Details about the volumes seen relative to allowable volumes
500 (Internal Server Error)	A 500 means that something bad has happened and it was Shipium's fault. It is possible that retrying a 500 error will succeed.	Details about the nature of the internal error. For 500 errors, an additional boolean field `retry` will exist with a value of `true` for those errors for which a retry is warranted and `false` if a retry is unlikely to succeed.
502 (Bad Gateway)	A 502 may be returned if a required external resource is unavailable and no backup (e.g., cache or secondary resource) is available.	Details about the nature of the external entity that returned this error
503 (Service Unavailable)	A 503 may be returned during certain timeframes in which the service has been taken offline for some reason. This should be very rare.	Details about why the service is unavailable and when it is expected to be available again, if known
504 (Gateway Timeout)	Similar to a 502, a 504 is specifically related to timeouts from required external resources.	Details about the nature of the external entity that caused this error

Common questions, issues, and answers

Difficulty calling the Shipium APIs

If you're experiencing errors calling any of Shipium's APIs, you can check our status page to determine any outages on Shipium's part or on the part of any of our dependencies. To access the status page, you'll log in to the Shipium Console. You'll select Service Status from the left navigation menu.

Invalid token error message

If you receive a message like
{"error":"invalid_token","error_description":"Invalid access token: xxxxxxxxxxxxxxxxxxxxx"}
this may be due to a failure to paste the ACCESS_TOKEN value. Make sure the whole value was copied, including the trailing =.

Unable to generate a label

If you are getting timeouts, and:

the timeouts are isolated to a single carrier, it is recommended to check their status page and contact carriers directly;
the timeouts are not isolated to a single carrier, we recommend using networking tools or command tools to trace the entire call to see what is accounting for the excess time. If you find that Shipium is a part of the timeout issues, please submit a ticket with your findings and we will work diligently to mitigate.

Missing shipment ID

If a shipmentId is not present for a given shipment, then we did not receive your request, you did not receive our response, or the shipment did not go through our system at all and may have gone through another system.

Need to add a new carrier

Please contact your Shipium implementation or success team. They will work to get all the relevant information from you and give you a timeline when this can be completed.

Need to update time-in-transit (TNT) values

Submit a ticket at the help center and select Carrier -> TNT. We will make this happen in a timely manner.

Items exceed all the packaging size dimensions

If you pass an item that exceeds the dimensions of all the packaging sizes that you have set up, the returned packagingTypeId will be "CUSTOM", indicating that you will need to create some kind of custom packaging for this particular product or products.

See Packaging Planner API for more information.

If you see a 4XX error from either label creation or the all-in-one shipment and label method

If a particular shipOption value is not possible, a 4XX error from either label creation or the all-in-one shipment and label method will give details about the problem.

See Ship Options for more information.

Details needed for why a carrier was selected

If you'd like more information about why a carrier was selected during the carrier selection process, you can view the Shipium details page. At the bottom, you’ll find a table of filters listing reasons why certain carrier methods were filtered out. You can find more information in Evaluated Service Methods.

If you need to contact Support

You can email us at [email protected]. Questions will be answered within 24-48 hours. If they involve an issue that needs to be fixed, we will also create an issue in our issue-tracking system and provide updates on that issue.

You can find more details about reaching out to our Support staff in
Contact Shipium Support.