> 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/order-api/order-api/error-handling/response-schemas-and-status-codes.md). # Response schemas and status codes ## Response Schema ### Schema 1 Used for: `401`, `403`, `404`, and the `default` response on all endpoints. ```json { "type": "string | null", "title": "string | null", "status": 400, "detail": "string | null", "instance": "string | null" } ``` ### Schema 2 Used for `400` on: `GET /Order/{brandOrderReference}`, `GET /Order/{brandOrderReference}/Transaction/{transactionReference}`, `POST /Comment`, and `POST /Replacement`. ```json { "code": 1, "message": "Invalid BrandOrderReference" } ``` ### Schema 3 Used for `400` on: `POST /Order`, `PUT /ContactDetails`, `POST /OrderActivity`, `POST /LineItemActivity`, `POST /LineItem`, `PATCH /LineItem`, `POST /Appeasement`, `POST /LineItemAppeasement`, `POST /Allocation`. ```json [ "Validation error message 1", "Validation error message 2" ] ``` *** ## HTTP Status Code Reference
CodeMeaningBody SchemaRecoverable?Notes
200OKVaries by endpointN/AGET operations, Comment, UpdateApproval
202Accepted (async)OrderTransactionApiResponseN/AMost write operations — see Section 9
400Bad RequestError, string[], or ProblemDetails — varies✅ YesFix payload before retrying
401UnauthorizedProblemDetails✅ YesRefresh token and retry once
403ForbiddenProblemDetails⚠️ NoPermissions issue — escalate
404Not FoundProblemDetails✅ PartialVerify path parameters
500Internal Server ErrorNone⚠️ MaybeNo body — use exponential backoff
defaultUnexpected errorProblemDetails⚠️ VariesCatch-all — see Section 3
### Status Code Exposure Per Endpoint
Endpoint200202400401403404500default
POST /{tenantCode}/Order✅✅✅✅✅✅✅
GET /{tenantCode}/Order/{ref}✅✅✅✅✅✅
GET /{tenantCode}/Order/{ref}/Transaction/{tRef}✅✅✅✅✅✅
PUT /{tenantCode}/Order/{ref}/ContactDetails✅✅✅✅✅✅
POST /{tenantCode}/Order/{ref}/OrderActivity✅✅✅✅✅✅✅
POST /{tenantCode}/Order/{ref}/LineItemActivity✅✅✅✅✅✅✅
POST /{tenantCode}/Order/{ref}/LineItem✅✅✅✅✅✅✅✅
PATCH /{tenantCode}/Order/{ref}/LineItem✅✅✅✅✅✅✅✅
POST /{tenantCode}/Order/{ref}/Appeasement✅✅✅✅✅✅✅✅
POST /{tenantCode}/Order/{ref}/LineItemAppeasement✅✅✅✅✅✅✅✅
POST /{tenantCode}/Order/{ref}/Replacement✅✅✅✅✅✅✅✅
POST /{tenantCode}/Order/{ref}/Allocation✅✅✅✅✅✅✅✅
POST /{tenantCode}/Order/{ref}/Comment✅✅✅✅✅
*** ## The `default` Response This is the catch-all for any HTTP status code not explicitly listed — including `422 Unprocessable Entity`, `429 Too Many Requests`, `503 Service Unavailable`, or upstream gateway errors. Treat `default` as a real code path in every error handler. {% code expandable="true" %} ```javascript async function handleOrderApiResponse(response, endpoint) { const knownCodes = [200, 202, 400, 401, 403, 404, 500]; if (!knownCodes.includes(response.status)) { // This is a `default` response — parse as ProblemDetails const err = await parseOrderApiError(response); console.error(`Unexpected status ${response.status} on ${endpoint}:`, err); throw new UnexpectedApiError(response.status, err); } // Handle known codes below... } ``` {% endcode %} ## Authentication & Authorization Errors ### 401 Unauthorized `401` uses the `ProblemDetails` schema. It is documented on most — but not all — write endpoints. | Cause | Fix | | ------------------------------ | ---------------------------------------------------- | | Missing `Authorization` header | Add `Authorization: Bearer ` to every request | | Expired JWT | Refresh the token and retry once | | Malformed or invalid token | Re-authenticate to obtain a valid token | {% code expandable="true" %} ```javascript async function callWithRefresh(url, options, getToken, refreshToken, maxAttempts = 2) { for (let attempt = 0; attempt < maxAttempts; attempt++) { const token = await getToken(); const response = await fetch(url, { ...options, headers: { ...options.headers, Authorization: `Bearer ${token}` }, }); if (response.status !== 401) return response; if (attempt < maxAttempts - 1) { console.warn(`401 on attempt ${attempt + 1} — refreshing token.`); await refreshToken(); } } throw new AuthError("Authentication failed after token refresh."); } ``` {% endcode %} ### 403 Forbidden `403` uses `ProblemDetails` and is documented on **every** endpoint. | Cause | Fix | | ------------------------------------------------------ | ----------------------------------------------------- | | Token lacks required scope | Contact | | `tenantCode` in path does not match the token's tenant | Confirm tenantCode matches the authenticated identity | | Feature not enabled for the tenant | Verify feature activation with ESW | `403` is not resolved by refreshing the token. Do not auto-retry — escalate to ESW support. *** ## 400 Bad Request The `400` body schema varies across endpoints. Applying the wrong parser will fail silently or throw a runtime error. ### 400 Schema Mapping | Endpoint | 400 Schema | | ------------------------------------- | ---------------- | | `GET /Order/{brandOrderReference}` | `Error` object | | `GET /Order/{ref}/Transaction/{tRef}` | `Error` object | | `POST /Comment` | `Error` object | | `POST /Replacement` | `Error` object | | `POST /Order` | `string[]` array | | `PUT /ContactDetails` | `string[]` array | | `POST /OrderActivity` | `string[]` array | | `POST /LineItemActivity` | `string[]` array | | `POST /LineItem` | `string[]` array | | `PATCH /LineItem` | `string[]` array | | `POST /Appeasement` | `string[]` array | | `POST /LineItemAppeasement` | `string[]` array | | `POST /Allocation` | `string[]` array | ### Schema-Aware 400 Handler {% code expandable="true" %} ```javascript async function handle400(response, endpoint) { const err = await parseOrderApiError(response); switch (err.schema) { case "validationArray": console.error(`[400] Validation errors on ${endpoint}:`); err.errors.forEach((msg, i) => console.error(` [${i}] ${msg}`)); throw new ValidationError(endpoint, err.errors); case "Error": console.error(`[400] Error on ${endpoint}: [${err.code}] ${err.message}`); throw new ApiError(err.code, err.message); case "ProblemDetails": console.error(`[400] Problem on ${endpoint}: ${err.title} — ${err.detail}`); throw new ProblemError(err.title, err.detail, err.instance); default: throw new Error(`[400] Unparseable error on ${endpoint}: ${err.raw}`); } } ``` {% endcode %} --- # 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/order-api/order-api/error-handling/response-schemas-and-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.