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）
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	未ルーティング / 指定拠点にピック対象なし
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）
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（<barcode>|<shipmentId>）形式不正 / 旧規格（受理せず再印刷案内。いずれも 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）
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 を返します:

{ "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 / channel_not_found / amount_inconsistency / out_of_range / invalid_timestamp	当該行を reject
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 概要）
• ラベル発行失敗: 確保状態は巻き戻さず last_label_error に記録（Address Recovery でリカバリ）