Getting started

Errors and limits

Every error has the same shape, and the status code tells you whether retrying can help.

Error shape

409 Conflict

{
  "error": {
    "code": "insufficient_stock",
    "message": "Not enough stock for one or more products.",
    "details": [
      {
        "product_id": "TSHIRT-RED-M",
        "requested": "5",
        "available": "2"
      }
    ]
  }
}

code is stable and safe to branch on. message is for people and may change. details is present when there is something specific to point at.

Status codes

200: Success. On POST /orders, also a repeat of an order already placed ("duplicate": true).
201: An order was created and confirmed.
400validation_failed: Something in the request is wrong. details lists { path, message }. Fix it before retrying.
401unauthorized: Missing, unknown or revoked key.
403forbidden: The company’s account is not active, or its plan excludes orders and inventory.
404not_found: No such product, customer or order — in this company.
405validation_failed: GET or DELETE on the MCP endpoint, which takes POST only.
409insufficient_stock: Not enough stock to fill an order. Nothing was created.
413validation_failed: Request body too large (32 KB for orders).
415validation_failed: Body was not application/json.
422unprocessable: The company has no active stock location.
429rate_limited: Too many requests. Wait Retry-After seconds.
500internal: Our fault. Safe to retry; for orders, with the same external_reference.

Retrying

Retry on a network error, a timeout, 429 (after Retry-After) and 5xx, with exponential backoff.
Do not retry any other 4xx unchanged — the answer will be the same.
Order creation is idempotent on external_reference, so retrying it can never create two orders.

Limits

60 requests per minute per key. MCP tool calls count as requests.
Up to 50 products per catalogue page, 50 lines per order and 5 active keys per company.
Photo links expire after 10 minutes. Fetch them when you need them; do not store them.