> For the complete documentation index, see [llms.txt](https://lmile.gitbook.io/lmile-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://lmile.gitbook.io/lmile-docs/reference/error-codes.md). # Error Codes 全公開 API 共通のエラー体系です。各エンドポイント固有のエラーは各ページの「エラー」セクションを参照してください。 ## 共通 HTTP ステータス | Status | 条件 | レスポンス例 | | :----: | --------------------------------- | --------------------------------------------------------------------------------------------- | | `400` | ボディ形式エラー / JSON パース失敗 | `{ "ok": false, "error": "shop required" }` / `{ "ok": false, "error": "invalid json body" }` | | `401` | `x-ingest-secret` 不一致 / 失効済み | `unauthorized` | | `403` | ボディの `shop` が API キーのスコープ外 | `{ "ok": false, "error": "shop not authorized for this key" }` | | `405` | 許可されていないメソッド | `method_not_allowed` | | `422` | 解決失敗等（`ok:false`、`error_kind` 付き） | `{ "ok": false, "error_kind": "location_unresolved", "error": "no location for ..." }` | | `500` | サーバー内部エラー | `{ "ok": false, "error": "..." }` | | `503` | サーバー側のシークレット未設定 | `{ "ok": false, "error": "INGEST_SECRET not configured" }` | ## `error_kind`（422 / 404 / 409） 解決・検証の失敗は `error_kind` で機械判別できます。代表値: | `error_kind` | 主な API | 意味 | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `invalid_payload` | Ingestion / Configuration / Webhooks / WMS Shipping Request | 必須欠落・不正値（WMS Shipping Request では `payload.action` 不一致・`order_detail` 非配列） | | `lambda_http_error` / `lambda_error_response` / `lambda_invalid_json` / `lambda_timeout` / `network_error` / `instruction_not_renderable` / `wms_url_not_configured` | WMS Shipping Request | WMS への送信失敗（HTTP エラー / エラー応答 / 非 JSON / タイムアウト / 接続不能 / 出荷指示を組み立てられない。いずれも `502`）/ 送信先未設定（`503`）。エラーでも送信記録は残り `request_id` が返る | | `invalid_destination_url` | Configuration / Webhooks | `destinationUrl` が https でない、または IP アドレス・`localhost`・`.internal`・`.local` のホスト | | `location_unresolved` / `location_ambiguous` | Inventory / MFC Inventory / Stocktake / Inventory Holds / Configuration / Routing (orders/shipped) | 拠点が解決できない / 複数候補 | | `location_not_derived` | Inventory（channel-available） | 外部倉庫の拠点（在庫数を別の送り手が送る拠点）ではない | | `insufficient_available` / `product_not_found` | Inventory Holds | 取り置ける上限（取り置き前の販売可能在庫 − 他の参照 ID の取り置き）を超えた（`409`・`detail.holdable` 付き）/ `barcode` が商品マスター未登録（`422`）。いずれもリクエスト全体を反映しない | | `fulfillment_source_unresolved` / `fulfillment_source_no_members` | Routing | 出荷元が無い / 有効メンバーが無い | | `unit_not_switchable` / `transfer_in_progress` | Source Change (`mode=switch`) | 即時切替の対象外（`allocated`/`secured` 以外・ピック済み）/ 進行中の返送ケースあり（いずれも `409`） | | `shipment_has_siblings` / `consolidation_group_member` | Source Change (`mode=switch`) | 同一レグに他の active 単位がある / MFC 集約グループのレグ（いずれも `409`・返送フローを使用） | | `location_not_member_of_source` | Routing | 指定在庫ロケーションが出荷元のメンバーでない | | `not_found` / `order_not_found` / `unit_not_found` / `routing_order_not_found` | Routing / Fulfillment / Oversell / Customer Orders / Shipment Delivery | 注文・単位が存在しない（`404`。Customer Orders では email 不一致も同じ `order_not_found`。Shipment Delivery は `routingOrderId` が同一 shop に無い） | | `order_cancelled` | Routing (update / orders/shipped) / Shipment Delivery | 取消済注文の更新・出荷済み登録（`409`） | | `leg_not_external` | Routing (orders/shipped/cancel) | `/orders/shipped` で登録したのではない生きた出荷がある注文の取消（`409`。`/api/routing/cancel` を使う） | | `invalid_transition` / `unit_not_changeable` | Oversell | 不正なステップ遷移 / 対象単位の状態不一致（`409`） | | `invalid_state` | Stocktake / External Fulfillment (ship) / Shipment Collect / Shipment Unsecure | 確定できないセッション状態（`422`。`not_found` = セッション無し。確定済みは `ok:true` + `already_committed` で no-op）/ 確保済・梱包中以外からの出荷済み報告（`409`。既に shipped は `ok:true` + `noop` の no-op）/ 確保済以外からの集荷・集荷対象の単位が無い（`409`）/ 出荷済み・取消済みの出荷の確保解除（`409`） | | `not_routed` / `location_not_in_picking_list` | Picking List | 未ルーティング / 指定拠点にピック対象なし | | `delivery_estimate_failed` | Picking List（batch・CSV） | お届け予定日を組めない注文がある（`500`）。CSV は作らない | | `validation_failed` | Address Recovery | 国内必須住所の欠落（`missing[]` 付き） | | `not_an_mfc_location` / `not_a_return_destination` | Fulfillment / Source Change | 指定拠点の種別不一致 | | `invalid_shelf_code` / `shelf_code_similar_to_tracking` | Shelf / MFC Inventory | 棚コード形式不正（`422`）/ 棚コードが追跡番号の類似値（誤スキャン・`422`） | | `shipment_not_found` / `ambiguous_tracking_number` / `shipment_status_not_linkable` | Shelf Link / Shelf Lookup / Secure Scan / Secure by Tracking / Shipment Memo / External Fulfillment / Shipment Collect | 追跡番号・ユニットQR の `shipmentId`・メモ対象 `shipmentId`・fulfill-job / fulfill-result / ship / collect の `shipmentId` に該当 shipment なし（`404`）/ 複数該当（`409`）/ 紐付け可能範囲外（`409`） | | `not_store_pickup` / `already_handed_over` / `pickup_requires_inventory_location` / `pickup_not_allowed_with_allocation_none` / `store_pickup_order` | Store Pickup / Routing / Fulfillment | 店舗受け取りの注文ではない（`422`）/ `ready` を引渡し済みの荷物に送った（`409`）/ `deliveryMethod: pickup` で出荷元に在庫ロケーションが複数あるのに `inventoryLocationId` が無い（`422`）/ `pickup` と `allocation: none` の組み合わせ（`422`）/ 受け取りの荷物を出荷確定で出荷済にしようとした（`422`。`store-pickup/handover` を使う） | | `shipment_already_linked` / `shelf_already_linked` | Shelf Link | shipment が別棚へ紐付け済 / 棚が別 shipment に占有済（`409`） | | `shelf_qty_below_active` | Shelf Inventory（`pick` / `move` の付け替え / `adjust` / `condition-move`）/ MFC Inventory / Stocktake | 減らした結果、その商品の棚の合計が注文に引き当て済みの数を上回る状態から下回る状態に変わる（`409`）。何も変更されません。`shelfTotal` / `shelfTotalAfter` / `active` を返します | | `insufficient_condition_qty` / `condition_unresolved` / `condition_master_missing` | Shelf Inventory（`condition-move`） | 良品以外の元の数が不足（`409`）/ 状態コードが shop に無い・無効（`422`）/ shop に既定の状態が無い（`422`） | | `session_already_open` / `shelves_still_counting` | Stocktake | 拠点に進行中のセッションがある（`409`・`sessionId` を返す）/ 締めていない棚がある（`409`・`shelves[]` を返す） | | `book_quantity_unavailable` | Stocktake（`commit`・店舗） | その拠点に取り込み元の生の在庫数が一度も届いていない（`422`）。帳簿数が作れないので承認しない | | `not_self_inventory_location` | Shelf Inventory / MFC Inventory | MFC ではない拠点に棚の行を作ろうとした（`422`）。棚ごとの在庫を持つのは MFC（`location_type` が `mfc`、または `mfc_enabled`）だけです。既にある行を減らす操作は止めません | | `shelf_occupied_by_different_barcode` / `insufficient_shelf_qty` | Shelf Inventory / MFC Inventory | 同一棚に別 barcode 占有（Shelf Inventory のみ）/ 在庫不足（Shelf Inventory の `pick`・MFC Inventory の `mode=adjust` で在庫が負になる行。いずれも `409`） | | `invalid_qr` / `legacy_qr` | Shelf Lookup / Pick / Secure Scan | ユニットQR（`\|`）形式不正 / 旧規格（受理せず再印刷案内。いずれも `422`） | | `unit_not_securable` | Secure Scan / Secure by Tracking | 確保可能な unit が無い（Secure Scan は 取消済 / 売越し / picked 済のみ等。Secure by Tracking は `status=allocated` が無い。`409`・`unitStatuses[]` 付き） | | `shelf_decrement_failed` / `insufficient_shelf_qty` / `shelf_occupied_by_different_barcode` | Shelf Pick / Secure Scan（棚QR時）/ Place Label | 集荷・確保・③ラベル配置で保管棚から商品を引けない（棚 0 / 別 barcode 占有）。棚 −1 とマーカーを原子確定する経路（LM-1121）で棚 −1 が不能なため `picked_at` / `shelf_released_at` を立てず `409` で表面化（黙って確定して phantom／売越を作らない） | | `transfer_required` | Units (secure) / Secure Scan / Secure by Tracking / Shelf Pick / Fulfillment (`shipped`) / External Fulfillment (ship) / Shipment Collect | 対象 unit が倉庫間移動（出荷元変更）フロー中で通常出荷操作を進められない（`409`・行き先 / バルク所属を `units[]` に同梱） | | `collect_depart_failed` | Shipment Collect | 集荷時の棚 −1 原子処理（LM-1121 の depart RPC）が失敗（`409`・`unitId` 付き。処理済みの単位は集荷済みのまま = 再送で残りだけ前進） | | `unit_not_secured` / `unit_already_picked` / `shelf_already_released` / `no_allocation_leg` / `transfer_in_progress` | Shipment Unsecure | 確保済みを解除できない単位（`409`・`unitId` 付き）: 確保済みでない / 集荷済み / 確保のときに棚から出した / 転送されてくる荷物の出荷 / 出荷元変更・返送の途中 | | `label_already_issued` | Shipment Collect | 配送ラベルを発行済みの出荷に手書きの送り状の追跡番号を送った（`409`。発行済みの番号は書き換えません） | | `pickup_already_requested` / `pickup_not_active` / `pickup_not_found` | Carrier Pickup | 既に生きた集荷依頼に入っている出荷が含まれる（`409`・既存の `prn` / `pickupDate` 付き）/ 取消済み・失敗済みの依頼を取り消そうとした（`409`）/ `pickupId` が該当なし（`404`） | | `shipment_not_pickupable` / `pickup_source_mixed` / `pickup_carrier_mismatch` / `pickup_destination_country_missing` | Carrier Pickup | 取消済み・出荷済み・アーカイブ済み・ラベル未発行の出荷が含まれる（`422`・`shipments[]` に該当全件と `reason`）/ 出荷元が複数にまたがる（`422`）/ UPS 以外が混在（`422`）/ 配送先の国が不明で個口内訳を組めない（`422`） | | `pickup_address_invalid` | Carrier Pickup | 依頼時に上書きした集荷先住所の項目が欠けている（`422`・足りない項目名を `error` に列挙。既定値では埋めない） | | `pickup_config_invalid` / `pickup_config_missing` / `ups_pickup_failed` / `ups_pickup_cancel_failed` | Carrier Pickup | 拠点の集荷設定が不正（`422`）/ 取消時に設定が見つからない（`422`）/ キャリアが依頼・取消を拒否（`502`・キャリアの応答をそのまま `error` に載せる） | | `pickup_finalize_failed` / `pickup_prn_unknown` | Carrier Pickup | キャリアは集荷を受け付けた（`error` に受付番号あり）が、こちらの記録に失敗（`500`・出荷は依頼済みのまま）/ 受付番号が記録されていない依頼を取り消そうとした（`409`。キャリア側に集荷が残っている可能性があるので自動解除しない） | | `not_transfer_target` / `batch_route_mismatch` | Transfer | スキャン unit が移動対象でない（`unitStatuses[]` 付き）/ ケースの経路がバルクと不一致（いずれも `422`） | | `batch_not_found` / `batch_not_open` / `batch_not_dispatched` | Transfer | バルクが存在しない（`404`）/ `open` でないので追加・取消不可 / 未発送なので受領不可（いずれも `409`） | | `already_in_batch` / `not_in_batch` / `not_in_this_batch` | Transfer | 別バルク所属（`409`）/ 取消対象が別バルク所属（`409`）/ 受領スキャンが当該バルク非所属（`422`） | | `inbound_transfer_same_source` / `no_active_units` | Transfer | 入荷転送の移動元と移動先の出荷元が同一（`422`）/ 出荷に有効な単位が無い（`422`） | | `inbound_batch_not_manually_receivable` | Transfer | 入荷転送は配達完了検知で自動受領するためスキャン受領できない（`409`） | | `empty_batch` / `unit_not_dispatchable` / `unit_not_receivable` | Transfer | 内容物 0 件で発送不可（`422`）/ 並行更新で発送対象外（`409`）/ `return_in_transit` でなく受領不可（`409`・`caseStatuses[]` 付き） | | `origin_unresolved` / `destination_unresolved` / `same_location` | Stock Transfer | 出庫元 / 入庫先の拠点参照が解決できない / 出庫元と入庫先が同一（いずれも `422`） | | `not_editable` / `not_deletable` | Stock Transfer | 出庫後などで明細編集不可（set/remove/update-lines）/ 出庫後で削除不可（delete。取消は cancel）（いずれも `422`） | | `approval_required` / `rejected` / `illegal_transition` | Stock Transfer | 承認前の出庫（`422`）/ 却下済みの出庫（`422`）/ その状態からできない遷移（approve・reject・ship・receive。`422`） | | `insufficient_transferable_qty` | Stock Transfer | 出庫数が移動可能量（棚合計 − 引き当て済み）を超過（売越防止・ship。`422`・`transferable`/`shelfSum`/`activeCount` 付き） | | `invalid_quantity` / `destination_shelf_required` / `modification_requested_locked` | Stock Transfer | 受け入れ + 不良が出庫数超過 / 自社在庫の受領に棚コード無し / 修正依頼中で受領ロック（receive。いずれも `422`） | | `not_cancelable` / `restore_failed` | Stock Transfer | `receiving`/`received` からは取消不可 / 出庫済みの棚復元に失敗し取消を確定しない（cancel。いずれも `422`） | | `not_receiving` / `modification_request_already_open` / `no_open_modification_request` | Stock Transfer | 入庫検品中でなく修正依頼を起票不可 / 依頼が既に開いている（1 件のみ）/ 完了・取消できる依頼が無い（いずれも `422`） | | `data_inconsistency` | Shelf Lookup / Operator | unit / shipment が指す注文の欠落（`500`） | | `missing_token` / `invalid_token` | Operator | operator JWT 未提示 / 不正・失効（`401`） | | `invalid_credentials` / `invalid_refresh_token` | Operator Login | ログイン失敗（メール存在有無は漏らさない）/ refresh token 不正（`401`） | | `invalid_code` | Operator Login | 確認コードが誤り / 期限切れ（原因詳細は漏らさない。`401`） | | `invalid_id_token` | Operator Login | Google ID token が不正 / 失効（原因詳細は漏らさない。`401`） | | `shop_not_authorized` | Operator | 要求 `shop` がスタッフの束縛 shop 外（`403`） | | `invalid_code` / `wrong_location` / `not_changeable` | Visit Check-in | QR が予約のものとして読めない（`400`）/ 予約が別の拠点のもの（`409`）/ 予約が確定していない（`409`） | | `rate_limited` | Operator Login | ログイン / 更新の試行回数上限（`429`） | | `auth_unavailable` | Operator Login | 認証基盤に到達できない（`503`。フォールバックなし。アカウント削除でも使用） | | `confirmation_required` | Operator Login (account/delete) | アカウント削除に `confirm: true` が無い（`400`） | | `demo_account_protected` | Operator Login (account/delete) | デモアカウントは削除不可（`403`） | | `audit_error` | Operator Login (account/delete) | 削除監査の記録に失敗（`500`） | | `product_not_found` | Operator Lookup / MFC Inventory | バーコードに該当商品なし（Operator Lookup は `404`。MFC Inventory は `422` でバッチ全体を中断） | | `invalid_status` | Operator Lookup / Queues | 売越しケース検索 / 出荷作業キュー一覧の `status` が許可値外（`400`・`allowed[]` 付き） | ## バリデーションエラー（Routing 系） Routing / Fulfillment / Oversell 系のバリデーション失敗は `error_kind`（422）ではなく **`400` + `invalid_input`** を返します: ```json { "ok": false, "error": "invalid_input", "details": [{ "path": "lines.0.quantity", "message": "..." }] } ``` ## レスポンスボディ内の行単位エラー HTTP `200` でも、行単位の不備はレスポンス内の配列で返り、正常行の処理は継続します（silent skip しません）。 | API | 配列 | code / reason | 説明 | | ---------------------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Products | `errors[]` | `barcode and product_name required` | 必須欠落（該当行 skip） | | Inventory Snapshot / Available | `unresolved[]` | `product_not_found` / `missing_barcode` / `missing_on_hand_qty` / `missing_available_qty` / `missing_available_delta` / `invalid_as_of` | barcode 未登録・必須欠落（`missing_on_hand_qty` は snapshot、`missing_available_*` は available の `mode` 対応値）・`as_of` 不正（該当行 skip） | | Inventory Available (delta) | `clamped[]` | — | `available_qty` が負になり 0 にクランプ | | Inventory Snapshot / Available | `stale_skipped[]` | — | 行の `as_of` が既存 `inventory_as_of` より古く適用しなかった（古い読み値の上書き防止・幽霊在庫防止。LM-1154） | | Stocktake（`shelf-submit`） | `unresolved[]` | `product_not_found` / `condition_unresolved` / `missing_barcode_or_qty` / `negative_qty` | barcode 未登録・状態コード不明・必須欠落・負の数（該当行は記録しない。他の行は記録する） | | Stocktake（`commit`） | `held[]` | `counted_below_active` / `negative_after_delta` / `moved_while_counting` / `uncounted` / `book_source_mismatch` | 良品の棚合計が引き当て済みを「上回る → 下回る」に変わる商品の良品の行 / 差分を当てると負になる行 / 店舗で数えている間に動いた商品（`includeMoved: true` で通す）/ 店舗で帳簿にあるのに読まれなかった商品（`includeUncounted: true` で通す）/ 店舗で帳簿数の取り込み元が当てる先のコネクタと違う商品（通せない。取り込みを直して数え直す）。保留のまま再 commit で再評価（`{ shelfCode, barcode, condition, errorKind, … }`） | | Order Line Master | `errors[]` | `required` / `location_not_found` / `location_unresolved` / `location_ambiguous` / `channel_not_found` / `amount_inconsistency` / `out_of_range` / `invalid_timestamp` | 当該行を reject | | Order Line Master（customers） | `results[].status` | `transaction_not_found` / `invalid_email` | その取引に顧客を結び付けない（`transaction_not_found` は顧客を作る・`invalid_email` は作らない） | | Customers | `results[].status` | `stale_skipped` / `email_conflict` | その顧客を更新しない（`updated_at` が前回より古い / 変更後のメールアドレスを別の顧客が使っている） | | Order Line Master | `warnings[]` | `product_not_in_master_warning` | barcode 未登録だが投入（要マスター登録） | | Routing Orders / Reallocate | `shippingInstruction.unroutableLines[]` | `no_stock_anywhere` 等 | 引き当て不能の明細（HTTP `200`。引き当てられた unit が無いときは `status: no_stock`） | | Routing Orders / Reallocate | `shippingInstruction.serviceLines[]` | — | 非在庫サービス品（`sot.products.is_non_inventory = true`）の明細。エラーでも引き当て不能でもない分類 | | Retry Label | `shipments[].action="skipped"` | `already_issued` / `not_secured` / `no_label_config` 等 | 再発行 skip の理由付き返却 | | External Fulfillment (fulfill-job) | `generatable: false` + `reason` | `shipment_cancelled` / `already_shipped` / `order_not_found` / `order_cancelled` / `fulfillment_source_unresolved` / `no_active_lines` / `seller_sku_unmapped` | 発注対象外・発注不能の理由付き返却（`seller_sku_unmapped` は `unmappedBarcodes[]` 付き。silent skip しない） | | Share Analytics | `shares[].skipped` / `items[].skipped` / `events[].skipped` | `missing_required_field` / `missing_share_token_or_hash_secret` / `unknown_event_type` / `invalid_occurred_at` | 当該行のみ skip（reason + `source_id` 付き）。upsert 失敗は `errors[]` + HTTP `207` | ## 外部送信の失敗 外部システムへの送信（WMS dispatch / webhook / ラベル発行）の失敗は HTTP エラーにしません: * **WMS dispatch 失敗**: HTTP `200` のまま `ok: false` / `status: failed`（ルーティング自体は成功・保存済。`dispatches[]` に記録） * **webhook 送信失敗**: トリガー元 API のレスポンスに影響しません（outbox に `delivery_status: failed` を記録。[Webhooks 概要](/lmile-docs/webhooks/overview.md)） * **ラベル発行失敗**: 確保状態は巻き戻さず `last_label_error` に記録（[Address Recovery](/lmile-docs/fulfillment-api/address-recovery.md) でリカバリ） --- # 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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://lmile.gitbook.io/lmile-docs/reference/error-codes.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.