> For the complete documentation index, see [llms.txt](https://developer.esw.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.esw.com/package-api/package-api/error-handling/http-status-codes.md).
# HTTP Status Codes
{% hint style="warning" %}
#### `PUT /Package` returns 201
Most HTTP clients, middleware, and API gateways treat 201 as a success code but some older interceptors only accept 200. Ensure your client success check is `res.status >= 200 && res.status < 300`, not `res.status === 200`.
{% endhint %}
The Package API uses a specific and consistent set of HTTP status codes. Here is every code you will encounter, its meaning in this API's context, and the correct client response.
### HTTP status codes
HTTP status code reference
| Code | Name | Meaning in Package API | Retryable | Client action |
| --------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------- |
| `200` | OK | Success for GET, POST, DELETE. Note: POST /Package returning 200 does *not* mean label generation succeeded — always check `outcome`. | N/A | Inspect `outcome` on POST; use response body directly on GET |
| `201` | Created | Success for PUT /Package. Returns updated Package object. Note this is 201, not 200. | N/A | Treat as success; update stored package record |
| `204` | No Content | POST /Manifest only. Manifest record found but no matching packages resolved from the submitted `eShopPackageReferences`. | Investigate | Verify `eShopPackageReferences` are valid and Complete |
| `400` | Bad Request | Request body or query parameters failed validation. Body is a `string[]` of specific field violations (or ProblemDetails for LabelConfig). | No | Fix the request; log all error strings; do not retry without changes |
| `401` | Unauthorized | Bearer token missing, expired, or malformed. Body is `{ message, code }`. | Once | Refresh token once, retry original request; fail on second `401` |
| `403` | Forbidden | Token is valid but lacks permission for this brand/resource. Empty body. Occurs on Package and PopulateBlacklist endpoints. | No | Do not retry; escalate to platform team to check brand permissions |
| `404` | Not Found | Resource does not exist. Body is `string[]`. On POST /Manifest it means the manifest is not pre-registered, not that the manifest number is wrong. | No | Verify identifiers; do not retry; surface to operator or raise incident |
| `409` | Conflict | State or uniqueness violation. On POST: package reference already exists. On PUT/DELETE: package not in valid state. Body is `string[]`. | No | Use GET to inspect current state; branch by sub-type (see §`409`) |
| `422` | Unprocessable | POST /Package only. Business-rule violation that passed schema validation — e.g. weight exceeds service level limit. Body is a plain `string`. | No | Fix the business-level constraint in the request; do not retry |
| `500` | Internal Server Error | Unhandled server-side exception. LabelConfig endpoints return 500 for unexpected failures. Empty or minimal body. | Yes | Retry with exponential backoff (max 3 attempts); alert if persists |
| `default` | Unexpected Error | Catch-all for any status not explicitly listed. Body is `string[]`. Treat as a 500-class error. | Cautiously | Log full response status + body; retry once with backoff; escalate |
### API Specific Error Codes
The following lists the unique error responses that the Package API can return.
CreatePackage
| Code | Message | Description |
| ---- | -------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| 101 | RequiredBrandCode | The brand code has not been included in the request. |
| 301 | InvalidBrandCode | The brand code is not recognized in the system. |
| 400 | InvalidAsnRequest | An exception has been caught while processing the request. |
| 317 | RequiredOrderReferences | The order references are missing from the request. |
| 316 | RequiredPackageReferences | The package references are missing from the request. |
| 333 | PackageNotCreatedAsAlreadyExists | The package already exists in the system. |
| 325 | PackageNotCreated | The package could not be created. |
| 323 | EShopSetupError | FTP Site may be incorrectly configured in the database. |
| 316 | InvalidNumberOfPackageReferences | The number of packages in the request is greater than the maximum allowed packages (currently set to 300). |
| 999 | Error | Returned when the system encounters an exception when processing the Create Package request. |
| 1001 | PackageListMustBeSet | The package request is null. It must contain one or more packages in the request. |
GetPackage
| Code | Message | Description |
| ---- | -------------------- | ---------------------------------------------------------- |
| 101 | RequiredBrandCode | The brand code has not been included in the request. |
| 400 | InvalidAsnApiRequest | An exception has been caught while processing the request. |
UpdatePackage
| Code | Message | Description |
| ---- | ------------------------------------ | ---------------------------------------------------------- |
| 101 | RequiredBrandCode | The brand code has not been included in the request. |
| 316 | RequiredPackageReferences | The package references are missing from the request. |
| 317 | RequiredOrderReferences | The order references are missing from the request. |
| 332 | PackageNotUpdatedAsNothingHasChanged | No changes are made to the package details. |
| 400 | InvalidAsnApiRequest | An exception has been caught while processing the request. |
DeletePackage
| Code | Message | Description |
| ---- | ------------------------ | -------------------------------------------------------------------------------------------- |
| 328 | PackageNotFound | The system is unable to find the package. |
| 326 | PackageNotValidForDelete | The package is not valid for the delete action. |
| 327 | PackageDeleted | The package is deleted successfully. |
| 999 | Error | Returned when the system encounters an exception when processing the Delete Package request. |
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://developer.esw.com/package-api/package-api/error-handling/http-status-codes.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.