Error Handling

AI Tools

We provide a summary of the general and specific response status codes returned by the API. We also describe error handling. Each call returns a general status and can include an array of detailed response codes corresponding to a field.

Field-Specific Error Responses

We provide additional field-specific information any time the API returns 400-500 HTTP error responses. These specific codes are helpful for mobile app developers looking to localize error messages. Field-specific errors can range from 40000-50000.

{ "reason": "Invalid input", "errors": [ { "code": 40006, "field": "declinationModel.Reason", "reason": "The value provided is invalid.", "severity": "Error" } ] }

General Error Codes

Code	Status Message	Description	Sample Scenario
200	OK	Success	The request has been processed successfully.
201	Created	New Resource Created	Create a new listing in the uShip marketplace. This status code returns along with a location header. Example: POST https://api.uship.com/v2/listings/702707778
204	No Content	No content has been returned.	When updating a user's settings, if the PUT is successful, this status code returns.
204	Deleted	A resource has been deleted.	Applies after a DELETE call is successful.
400	Bad Request	The request cannot be completed.	Call contains invalid input and does not complete.
401	Unauthorized	Resource access is outside of user permissions.	When this code returns, we recommend debugging the authorization method. The user is not authorized. Check your authorization header for errors.
403	Forbidden	Access Denied.	If a user attempts to modify a resource that you do not own such as modifying another user's preferences, this error will return. For example, when updating an user's settings, if the PUT is not successful, this status code could return with field-level error.
404	Not found	Resource not found. Can also mean that the route does not exist.
405	Method Not Allowed	Resource does not support method. Resource method not yet available.	Updating to the URI https://api.uship.com/v2/savedSearches/Id/results Example response: The requested resource does not support http method 'PUT'.
409	Conflict	The server received a request conflict.
412	Precondition failed	Mostly used to support the API.
500	Internal Server Error	The server encountered an error.
501	Not implemented	This resource has not yet been implemented.	uShip Development either has not or is still creating the resource.
503	Service Unavailable	The server cannot handle the request at this time.	Usually indicates temporary server downtime.
504	Gateway Timeout	When the server is acting as a gateway and cannot retrieve a response in time.

Common Error Causes

The following items are common, easy-to-fix causes for errors that integrators may experience:

Exceeding character limits: Listing titles have a limit of 50 characters and Listing descriptions have a limit of 5000 characters.
Expired access token: Please refresh the access token as described on our Authentication page
Rate limiting: You may be exceeding your account's rate limits on calls per second or day. Please talk with your integration specialist when setting up your integration to find an optimal rate limit, if necessary.
Invalid Zip Codes: Zip code 10000, international zip codes, or same zip-to-zip test calls may generate errors when attempting to generate rates.
Case sensitive errors

Last updated on