> 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/checkout-api/checkout-api/error-handling/404-405-and-409-errors.md).

# 404, 405, and 409 Errors

### 404 Not Found

A `404` response means the `eShopWorldOrderNumber` provided in the request body could not be found in the ESW platform.

### Causes

| Cause                             | Description                                                                      |
| --------------------------------- | -------------------------------------------------------------------------------- |
| Incorrect `eShopWorldOrderNumber` | The ID does not match any order created by ESW for this retailer                 |
| Order not yet created             | The ESW order may not yet exist — timing issue in the checkout flow              |
| Wrong environment                 | The order ID was created in a different environment (e.g. production vs sandbox) |

### Handling

```javascript
if (response.status === 404) {
  const result = await parseConfirmationResponse(response);
  console.warn(`ESW order not found: ${payload.eShopWorldOrderNumber}`);

  // Check if a timed retry is appropriate (order may be in-flight)
  // Do NOT retry indefinitely — escalate if the order was expected to exist
  throw new OrderNotFoundError(payload.eShopWorldOrderNumber, result.errors);
}
```

{% hint style="warning" %}
A `404` is not a transient network error. Retrying with the same `eShopWorldOrderNumber` will continue to fail unless the underlying data issue is resolved.
{% endhint %}

***

### 409 Conflict — Duplicate Order

A `409` response means the server has detected a conflict — most likely that an order with the same `eShopWorldOrderNumber` or `retailerCartId` has already been confirmed.

### Causes

| Cause                             | Description                                                                 |
| --------------------------------- | --------------------------------------------------------------------------- |
| Duplicate `eShopWorldOrderNumber` | A confirmation for this ESW order number was already successfully submitted |
| Duplicate `retailerCartId`        | The retailer cart reference has already been used for a confirmed order     |
| Concurrent submission             | The same order was submitted twice simultaneously (race condition)          |

### Handling Strategy

`409` requires careful handling in an order-confirmation context. An auto-retry without checking the system state risks creating duplicate financial records.

{% code expandable="true" %}

```javascript
if (response.status === 409) {
  const result = await parseConfirmationResponse(response);

  // Step 1: Log the conflict with full context
  console.warn(
    `Order conflict detected. eSwOrderNumber=${payload.eShopWorldOrderNumber} ` +
    `retailerCartId=${payload.retailerCartId}`
  );
  result.errors.forEach((e) => console.warn(`  [Code ${e.code}] ${e.message}`));

  // Step 2: Check if the original confirmation already succeeded
  // Query your own order management system before deciding to retry
  const existingOrder = await lookupOrderByEswNumber(payload.eShopWorldOrderNumber);

  if (existingOrder?.isConfirmed) {
    // The order was already successfully confirmed — treat this as idempotent success
    console.info("Order already confirmed — no action needed.");
    return existingOrder;
  }

  // Step 3: If not confirmed locally, escalate — do not auto-retry
  throw new ConflictError(
    `Order ${payload.eShopWorldOrderNumber} conflicts with an existing record. ` +
    `Manual investigation required.`,
    result.errors
  );
}
```

{% endcode %}

{% hint style="warning" %}
Do not implement blind retry logic for `409`. In order-processing systems, a retry on a conflict can produce duplicate charges or fulfilled orders. Always verify the existing state before deciding on the next action.
{% endhint %}


---

# 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/checkout-api/checkout-api/error-handling/404-405-and-409-errors.md?ask=<question>&goal=<endgoal>
```

`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.