> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shipstream.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Response Codes and Errors

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.

<Expandable title="4xx Error Response JSON Schema">
  ```json title="JSON Schema" theme={null}
  {
    "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"]
  }
  ```
</Expandable>

# 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](#400-bad-request)
* [401 Unauthorized](#401-unauthorized)
* [404 Not Found](#404-not-found)
* [405 Not Allowed](#405-not-allowed)
* [409 Conflict](#409-conflict)
* [412 Not Supported](#412-not-supported)
* [422 Unprocessable](#422-unprocessable)
* [500 Internal Error](#500-internal-error)
* [503 Service Unavailable](#503-service-unavailable)
* [Other 5xx Errors](#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

```json Response Example theme={null}
{
  "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.

```json Response Example theme={null}
{
  "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.

```json Response Example theme={null}
{
  "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.

```json Response Example theme={null}
{
	"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.

```json Response Example theme={null}
{
  "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.

```json Response Example theme={null}
{
  "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.

```json Response Example theme={null}
{
  "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.

```json Response Example theme={null}
{
  "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.

```json Response Example theme={null}
{
  "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.

```json Response Example theme={null}
{
  "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.