A 4xx HTTP response code should be returned for all application level errors and the response should always contain a JSON-encoded body. If any non 2xx HTTP response code is returned then the request will have been fully rolled back and should have no impact on any data.

​
HTTP Response Codes

The different types of errors which may occur in the application (excluding any network or routing errors) typically belong to one of the following HTTP response codes: Examples for each of these response codes are provided below.

​
400 Bad Request

The server cannot or will not process the request due to something that is perceived to be a client error.

​
Request Not Valid

Response Example
{
  "errors": [
    {
      "type": "parameters",
      "message": "The supplied parameters are invalid.",
      "details": [
        {
          "key": "sort",
          "message": "Only two sort orders are allowed."
        }
      ]
    }
  ]
}

​
Parse Error

The server was not able to parse the request body or the decoded request body was not the proper data type.
Response Example
{
  "errors": [
    {
      "type": "parser",
      "message": "There was an error parsing the request.",
      "details": [
        {
          "key": "json",
          "message": "Syntax error."
        }
      ]
    }
  ]
}

​
OpenAPI Validation

Before the server begins to process the request it will validate the full request against the OpenAPI spec. Specifically, the parts of the request which are validated are:
  • Headers
  • Cookies
  • Body
  • Query
  • Path
  • Security Scheme
Any failure in validation against the OpenAPI spec will result in an openapi type error with the details describing which step failed validation in the key and a message describing the failure.
Response Example
{
  "errors": [
    {
      "type": "openapi",
      "message": "Request message failed OpenAPI spec validation.",
      "details": [
        {
          "key": "invalid_query_args",
          "message": "Parameter 'sort' has invalid value"
        }
      ]
    }
  ]
}

​
401 Unauthorized

The request requires user authentication. If the request lacks valid credentials, the server will respond with a “401 Unauthorized” error.
Response Example
{
	"errors": [
		{
			"type": "unauthorized",
			"message": "Invalid Global API Access Token: Token is expired.",
			"details": [
				{
					"key": "",
					"message": "The request requires valid user authentication."
				}
			]
		}
	]
}

​
404 Not Found

The server can not find the requested resource. In the context of this API, this will mean that the endpoint is valid but the resource itself does not exist or a resource that was referenced in the request does not exist.
Response Example
{
  "errors": [
    {
      "type": "not_found",
      "message": "The server could not find the requested resource."
    }
  ]
}

​
405 Not Allowed

The request method is known by the server but is not supported by the target resource.
Response Example
{
  "errors": [
    {
      "type": "not_allowed",
      "message": "The target resource does not support the requested method."
    }
  ]
}

​
409 Conflict

Errors that do not fit one of the other response types may use this response code.
Response Example
{
  "errors": [
    {
      "type": "generic",
      "message": "Unknown error"
    }
  ]
}

​
412 Not Supported

The request is known by the server but a required feature may be disabled or it is not supported by the requested API version.
Response Example
{
  "errors": [
    {
      "type": "not_supported",
      "message": "The requested resource is not supported in the API version specified. Please update to the latest version."
    }
  ]
}

​
422 Unprocessable

The request encountered an anticipated error during processing.
Response Example
{
  "errors": [
    {
      "type": "unable_to_process",
      "message": "There was an error processing the request.",
      "details": [
        {
          "key": "validation",
          "message": "A user with the same user name or email already exists."
        }
      ]
    }
  ]
}
Additional errors encountered may be given the type “application” and will typically include a more detailed message but not a details array.
Response Example
{
  "errors": [
    {
      "type": "application",
      "message": "Shipment cannot be deleted in its current status: Packing"
    }
  ]
}

​
500 Internal Error

An unexpected/internal error is an indication that something went wrong, possibly indicating a bug or a temporary service interruption. Although these errors should be exceedingly rare, you should anticipate that they may occur as these errors will likely not be returned in a JSON-encoded format.

​
503 Service Unavailable

The server is not ready to handle the request. Common causes are a server that is down for maintenance or that is overloaded.

​
Other 5xx errors

Any other 5xx range errors are likely due to a network or routing issue and should be temporary and will likely not have a predictable response format.