Error Handling
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