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.

Show 4xx Error Response JSON Schema

JSON Schema

{
  "type": "object",
  "properties": {
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "description": "The type of error.",
            "enum": ["application"]
          },
          "message": {
            "type": "string",
            "description": "An error message."
          },
          "details": {
            "type": "array",
            "description": "May provide more specific error details if available.",
            "items": {
              "type": "object",
              "properties": {
                "key": {
                  "type": "string",
                  "description": "The JSON path or other identifier for the key or parameter which is related to the error. "
                },
                "message": {
                  "type": "string",
                  "description": "A descriptive error message relating specifically to the `key` given."
                }
              },
              "required": ["key","message"]
            }
          }
        },
        "required": ["type","message"]
      }
    }
  },
  "required": ["errors"]
}

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:

400 Bad Request
401 Unauthorized
404 Not Found
405 Not Allowed
409 Conflict
412 Not Supported
422 Unprocessable
500 Internal Error
503 Service Unavailable
Other 5xx Errors

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.

Get Started

Common Features

Inventory API v1

Receiving API v1

Shipping API v1

System API v1

Response Codes and Errors

HTTP Response Codes

400 Bad Request

Request Not Valid

Parse Error

OpenAPI Validation

401 Unauthorized

404 Not Found

405 Not Allowed

409 Conflict

412 Not Supported

422 Unprocessable

500 Internal Error

503 Service Unavailable

Other 5xx errors

​HTTP Response Codes

​400 Bad Request

​Request Not Valid

​Parse Error

​OpenAPI Validation

​401 Unauthorized

​404 Not Found

​405 Not Allowed

​409 Conflict

​412 Not Supported

​422 Unprocessable

​500 Internal Error

​503 Service Unavailable

​Other 5xx errors

HTTP Response Codes

400 Bad Request

Request Not Valid

Parse Error

OpenAPI Validation

401 Unauthorized

404 Not Found

405 Not Allowed

409 Conflict

412 Not Supported

422 Unprocessable

500 Internal Error

503 Service Unavailable

Other 5xx errors