> 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/returns-api/grp-returns-api/error-handling/enum-reference.md). # Enum Reference All enums except `OrderItemSource` are strings. All use `x-ms-enum: { modelAsString: true }` — the API treats them as extensible strings at runtime, but only the documented values produce defined behaviour. #### Ingestion Layer Enums | Enum | Type | Values | Notes | | ----------------- | ------- | ----------------------------------------- | ---------------------------------------------- | | `ShippingStatus` | string | `"Unshipped"`, `"Shipped"`, `"Cancelled"` | Ingestion layer | | `WeightUnit` | string | `"Kg"`, `"Lb"` | Mixed case. See Section 14. | | `OrderItemSource` | integer | `0`, `1` | Only enum in this section that is not a string | #### Returns / OMS Layer Enums | Enum | Type | Values | Notes | | ------------------------ | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | | `ReturnMethod` | string | `"Postal"`, `"PUDO"`, `"Collections"` | How the shopper returns the item | | `ReturnType` | string | `"Normal"`, `"Undeliverable"`, `"BlindReturn"`, `"EUCoolingOff"` | Return classification | | `PaidBy` | string | `"Unpaid"`, `"Retailer"`, `"Shopper"` | Who pays return shipping | | `ReturnOrderStatus` | string | `"Created"`, `"Received"`, `"OnHold"`, `"Released"`, `"Processed"`, `"AddedToManifest"`, `"SentToRetailer"`, `"ReceivedByRetailer"`, `"RemovedFromManifest"`, `"Cancelled"`, `"Refunded"` | Full lifecycle. Used for filtering and update. | | `UpdateReturnItemStatus` | string | `"Accepted"`, `"Rejected"` | Only values accepted on `PUT` | | `ReturnItemStatus` | string | `"InProgress"`, `"Accepted"`, `"Rejected"`, `"RejectedNotReturned"`, `"Cancelled"` | Full item lifecycle. Read-only in responses. | | `ReturnOrderParty` | string | `"Shopper"`, `"CustomerService"` | Who initiated the return | | `ShippingStatus` | string | `"Unshipped"`, `"Shipped"`, `"Cancelled"` | OMS layer | | `ServiceType` | string | `"Express"`, `"Post"`, `"PUDO"` | Service classification | | `WeightUnit` | string | `"Kg"`, `"Lb"` | OMS layer | | `LocationType` | string | `"Store"`, `"Pudo"` | Location classification | #### Document & Location Enums | Enum | Type | Values | Notes | | ---------------------- | ------ | ----------------------------------------------- | ------------------------------------------------------- | | `DocumentType` | string | `"OutboundLabel"`, `"ReturnLabel"`, `"Invoice"` | `documentType` path param for the Get Document endpoint | | `ReturnDocumentType` | string | `"ReturnLabel"`, `"LastMileLabel"` | Used in document responses | | `ReturnDocumentStatus` | string | `"Processing"`, `"Ready"`, `"Failed"` | Document state in responses | | `RegenerateReason` | string | `"LabelFailed"`, `"LabelExpired"`, `"Unknown"` | Reason for label regeneration | | `RouteType` | string | `"Inbound"`, `"Outbound"` | Required on `GET /location/` | *** ### Field Constraint Reference #### `CreateOutboundOrderWebRequest` / `UpdateOutboundOrderWebRequest` | Field | Type | Notes | | --------------------------------------------- | ------------------ | ------------------------------------------------------------------------------ | | `orderReference` | string | Required in practice for create | | `canOverwrite` | boolean | Controls 409 vs overwrite on POST. Default `false`. | | `orderItems[].quantity` | integer (int32) | Positive | | `orderItems[].weight.weightUnit` | `WeightUnit` | `"Kg"` or `"Lb"` | | `orderItems[].unitPrice.amount` | number (double) | e.g. `70.2` | | `orderItems[].unitPrice.currency` | string | ISO 4217, e.g. `"USD"` | | `orderItems[].shippingInformation.statusDate` | string (date-time) | ISO 8601 UTC | | `orderItems[].dangerousGoods` | boolean | If `true`, `unitedNationsNumber` and `packingInstructions` should be populated | #### `SubmitOutboundShipmentWebRequest` | Field | Type | Notes | | ----------------------------------- | ------------------ | ---------------- | | `shippingDate` | string (date-time) | ISO 8601 UTC | | `shippingItems[].weight.weightUnit` | `WeightUnit` | `"Kg"` or `"Lb"` | | `shippingItems[].unitPrice.amount` | number (double) | | #### `CreateReturnOrderWebRequest` | Field | Type | Notes | | -------------------------- | -------------- | ---------------------------------------------------------------- | | `returnItems` | array | Min 1 item expected | | `returnItems[].reasonCode` | string | Agreed reason codes — check ESW configuration | | `returnMethod` | `ReturnMethod` | `"Postal"`, `"PUDO"`, `"Collections"` | | `returnType` | `ReturnType` | `"Normal"`, `"Undeliverable"`, `"BlindReturn"`, `"EUCoolingOff"` | | `paidBy` | `PaidBy` | `"Unpaid"`, `"Retailer"`, `"Shopper"` | | `cultureLanguageIso` | string | BCP-47 format, e.g. `"fr-FR"`, `"en-GB"` | | `weight.weightUnit` | `WeightUnit` | `"Kg"` or `"Lb"` | #### `UpdateReturnOrderWebRequest` | Field | Type | Notes | | -------------------------------- | ------------------------ | ------------------------------------- | | `status` | `ReturnOrderStatus` | Any of the 11 lifecycle values | | `returnItems[].returnItemStatus` | `UpdateReturnItemStatus` | **Only** `"Accepted"` or `"Rejected"` | | `weight.weightUnit` | `WeightUnit` | `"Kg"` or `"Lb"` | #### `GetTrackingEventsWebRequest` | Field | Type | Notes | | ------------------- | --------------- | -------------------------------------- | | `trackingReference` | integer (int64) | Must be a numeric type — not a string | | `emailAddress` | string | Optional shopper email for correlation | #### `GET /location/` — Required Query Parameters | Parameter | Type | Notes | | ----------------------- | ----------- | ------------------------------------- | | `identifier` | string | Tenant/brand code | | `CountryCode` | string | ISO 3166-1 alpha-2 | | `PostalCode` | string | | | `RouteType` | `RouteType` | `"Inbound"` or `"Outbound"` | | `CarrierServiceRouteId` | string | Must match a configured carrier route | *** ### Retry Strategy {% code expandable="true" %} ``` Response Received │ ├── 200 / 201 — Success (check body for partial errors if applicable) │ └── ✅ Process response. No retry needed. │ ├── 400 Bad Request (ValidationProblemDetails) │ ├── Read ALL entries in the errors dictionary. │ └── ❌ Do NOT retry without fixing every failing field. │ ├── 401 Unauthorized (ProblemDetails) │ ├── Refresh token → retry once. │ └── Still 401 → ❌ Stop. Check token scope. │ ├── 403 Forbidden (ProblemDetails) │ └── ❌ Do NOT retry. Check identifier match and permissions. │ ├── 404 Not Found (ProblemDetails) │ ├── GET /return-orders with no results → treat as empty [] ✅ │ └── All other 404s → ❌ Verify identifiers. Do not retry. │ ├── 409 Conflict (ProblemDetails) │ ├── label-requests → treat as idempotent success (label already issued) ✅ │ ├── outbound-orders → switch to PUT or set canOverwrite: true ⚠️ │ └── return-orders → check existing return orders before retrying ⚠️ │ ├── 422 Unprocessable Entity (ValidationProblemDetails — /location/ only) │ └── ❌ Do NOT retry. Fix semantic query parameters. │ └── 500 Internal Server Error (ProblemDetails or BaseResponse) ├── ⏳ Exponential backoff — max 3 retries. └── Persistent → ❌ Escalate. ``` {% endcode %} #### Retry Parameters | Scenario | Retryable | Delay | Max Retries | Notes | | --------------- | ---------------- | -------------- | ----------- | ----------------------------- | | `400` | ❌ No | — | 0 | Fix each failing field | | `401` | ✅ Once | Token refresh | 1 | One refresh, one retry | | `403` | ❌ No | — | 0 | Permissions/tenant issue | | `404` (list) | ✅ Treat as empty | — | 0 | Not a true error | | `404` (other) | ❌ No | — | 0 | Verify path params | | `409` (label) | ✅ Idempotent | — | 0 | Label exists — don't resend | | `409` (order) | ⚠️ Conditional | — | 0 | Fix request or use PUT | | `422` | ❌ No | — | 0 | Fix semantic params | | `500` | ✅ Yes | 1s exp backoff | 3 | With jitter | | Network timeout | ✅ Careful | 2s | 3 | Check for prior success first | *** ### Error Handling Checklist #### Request Construction * [ ] `Authorization: Bearer ` header is present on every request * [ ] `Content-Type: application/json` is set on all POST and PUT requests * [ ] `{identifier}` in the path matches the tenant scope of the Bearer token * [ ] For `GET /location/`, `identifier` is a **query parameter** — not a path parameter * [ ] The request body is never empty or `{}` — all POST/PUT endpoints require a meaningful body despite Swagger marking it `required: false` * [ ] `weightUnit` is `"Kg"` or `"Lb"` (mixed case) — not `"KG"`, `"LB"`, `"kg"`, or `"lb"` * [ ] `OrderItemSource`, if used, is an **integer** (`0` or `1`) — not a string * [ ] `UpdateReturnOrderWebRequest.returnItems[].returnItemStatus` uses only `"Accepted"` or `"Rejected"` — not any other `ReturnItemStatus` value * [ ] `status` on `UpdateReturnOrderWebRequest` uses a valid `ReturnOrderStatus` string * [ ] All `date-time` fields use ISO 8601 UTC format (`"2024-03-15T10:30:00Z"`) * [ ] `trackingReference` is sent as an `int64` (number), not a string * [ ] `canOverwrite` is set explicitly on `POST /outbound-orders` when re-creation of existing orders is intended * [ ] `dangerousGoods: true` items include `unitedNationsNumber` and `packingInstructions` * [ ] No extra/unknown fields — all request schemas use `additionalProperties: false` * [ ] `GET /location/` includes all four required query params: `identifier`, `CountryCode`, `PostalCode`, `RouteType`, `CarrierServiceRouteId` #### Response Handling * [ ] `POST /{id}/label-requests` success is `200` — not `201`. An absent `201` is not a failure. * [ ] `POST /{id}/outbound-orders` and `POST /{id}/orders/{ref}/return-orders` success is `201` * [ ] `400` parsing iterates the `errors` **dictionary** (`field → string[]`), not a flat array * [ ] `400` handles the case where `errors` is empty but `detail` is present * [ ] `500` on `GET /{id}/return-orders/{num}/{docType}` is parsed as `BaseResponse` (`userMessage` + `details`) — not `ProblemDetails` * [ ] `404` on `GET /{id}/return-orders` is treated as an empty result set — not a fatal error * [ ] `409` on label-requests is handled as idempotent — the label already exists, don't resend * [ ] `422` on `GET /location/` is handled identically to `400` — read the `errors` dictionary #### Auth * [ ] Token refresh is attempted universally on `401` — even on endpoints that don't document it * [ ] A `403` is never retried — it is escalated to resolve the `identifier`/permission mismatch * [ ] After one token refresh, a persisted `401` is treated as a hard failure, not retried further #### Observability * [ ] Every `errors` dictionary entry from `400`/`422` is logged individually with its field name * [ ] `identifier`, `orderReference`, and `returnOrderNumber` are included in all error log entries * [ ] `409` events on `POST /outbound-orders` are monitored — a spike indicates retry logic incorrectly re-creating orders * [ ] `500` events on the document endpoint (`BaseResponse`) log both `userMessage` and `details` * [ ] Persistent `500` errors are escalated with the full request (headers minus auth, body, path) and timestamp --- # 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/returns-api/grp-returns-api/error-handling/enum-reference.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.