Error Handling

HTTP Response Status Codes

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.

Code Status Message Description Sample Scenario
200 OK Success The request has been processed successfully. Lookup the list of address types.
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 returns. When updating an user's settings, if the PUT is successful, this status code returns.
204 Deleted A resource is deleted.
400 Bad Request The request cannot be completed for a reason such as invalid input.
401 Unauthorized Resource access not authorized. 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.

uShip-Specific 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. See specific method reference pages for descriptions and associated scenarios.

Example

JSON response

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

Adapted from various sources including https://developer.mozilla.org/en-US/docs/HTTP/Response_codes.