Errors

`insufficient_stock`

HTTP HTTP 409.

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

{
  "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
    }
  ]
}

When it happens

409. POST /api/v1/orders/{orderId}/reserve 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

Fix and resend409 contact_in_use · address_in_use · insufficient_stock
Do not retry. errors[] says what blocks the operation: fix that first.

Fields of errors[]

errors[].pathstring

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

Available options: items, spaces

errors[].itemIdstring

On insufficient_stock: the item, or the space when path is spaces, that is short.

errors[].requestednumber

On insufficient_stock: units the order needs.

errors[].availablenumber

On insufficient_stock: units available for the dates of the order.

errors[].shortfallnumber

On insufficient_stock: units missing (requested − available).

Returned by

1 operations

POST /api/v1/orders/{orderId}/reserve — 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`.

Was this page helpful?

Example