Troubleshooting Guide
Overview
There are some common issues and how to fix them.
API response code errors
The Shipium APIs follow the API Response Codes standards unless otherwise specified.
Broadly, the error responses 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 generally 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) attempting to utilize a service that your company 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, label id, etc.) 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 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 our 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, secondary resource, etc.) is available. | Details about the nature of the external entity which 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, but specifically related to timeouts from required external resources. | Details about the nature of the external entity which caused this error. |
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 =.
Items exceed all the packaging size dimensions
If you pass an item that exceeds the dimensions of all of 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 Package Sizing Flow 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 Shipment Ship Option Overview for more information.
If you need to contact Support
You can email us at [email protected]. Questions sent to help will be answered within 24-48 hours and 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.
More information:
Contacting Shipium Support
Updated 7 months ago