*REST API › Errors*

# `insufficient_stock`

> HTTP HTTP 409.

HTTP status: `409` · Problem type: `https://docs.filmo.io/errors/insufficient_stock`

## When it happens

409. [`POST /api/v1/orders/{orderId}/reserve`](https://docs.filmo.io/rest-api/endpoint-reference/orders/reserve-an-order) refused because there is not enough stock for the dates of the order. `errors` has one entry per short item or space, with `itemId`, `requested`, `available` and `shortfall`; `path` is `items` or `spaces`.

## What to do

Use the entries of `errors[]` to reduce the quantities, change the dates, or free stock elsewhere, then reserve again. Check availability before reserving to avoid the round trip.

## Retry

| Condition | What to do | Note |
| --- | --- | --- |
| 409 contact_in_use · address_in_use · insufficient_stock | Fix and resend | Do not retry. `errors[]` says what blocks the operation: fix that first. |

## Fields of errors[]

| Name | Type | Description |
| --- | --- | --- |
| `errors[].path` | string | Path of the offending field in dot and bracket notation (`lines[0].itemId`); empty for the whole body. On `contact_in_use`, `address_in_use` and `insufficient_stock` it is one of a closed set, listed by code in `x-path-values`: the type of record that uses the contact or the address, or the kind of resource that is short (`items` or `spaces`). `items`, `spaces` |
| `errors[].itemId` | string | On `insufficient_stock`: the item, or the space when `path` is `spaces`, that is short. |
| `errors[].requested` | number | On `insufficient_stock`: units the order needs. |
| `errors[].available` | number | On `insufficient_stock`: units available for the dates of the order. |
| `errors[].shortfall` | number | On `insufficient_stock`: units missing (`requested` − `available`). |

## Example

*insufficient_stock*

```json
{
  "type": "https://docs.filmo.io/errors/insufficient_stock",
  "title": "Insufficient stock",
  "status": 409,
  "code": "insufficient_stock",
  "detail": "1 item does not have enough stock for the dates of the order; nothing was reserved. The detail is in errors",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c",
  "errors": [
    {
      "path": "items",
      "code": "insufficient_stock",
      "message": "Short by 2 of 5 units for the dates of the order",
      "itemId": "itm_9f3a2b",
      "requested": 5,
      "available": 3,
      "shortfall": 2
    }
  ]
}
```

## Returned by

- [`POST /api/v1/orders/{orderId}/reserve`](https://docs.filmo.io/rest-api/endpoint-reference/orders/reserve-an-order) — Reserve an order

## Through MCP

A tool call that fails comes back with `isError` set and the problem as structured content, with the same `code`.

---

Canonical URL: https://docs.filmo.io/rest-api/errors/insufficient_stock  
Last updated: 2026-10-25