Flow の監視と問題解決

Flow の実行をどこで監視するか、失敗した実行を壊れたノードまで読み解く方法、そして実際に遭遇する 5 つの失敗——症状、原因、自分でできる修正手順。

監視するもの#

• 実行モニター（Integration → Runs）：すべての Flow 実行が 1 つのリストに。Flow 名とバージョン、トリガー（スケジュール／イベント／手動）、ステータス（running、success、failed、retrying）、所要時間、処理件数。ステータスで絞ると失敗だけ見られます。
• 実行詳細：実行をクリックするとノード単位で見られます。各ステップの入力スナップショット、出力スナップショット、失敗ステップの正確なエラーメッセージ。常にここから始めてください。
• ログとデッドレター（Integration → Logs）：最終的に失敗した項目は、Flow、ノード、エラーとともにデッドレターキューに入ります。原因を直したら、デッドレターをリプレイしてその項目を再処理できます。不要なら破棄してください。
• 接続の健全性：最初のノードで認証エラーになる実行は、Flow ではなく接続の問題です。接続自体の「テスト」ボタンで数秒で再現できます。

以下の 5 つの失敗で、遭遇するほぼすべてのケースをカバーします。それぞれに症状、原因、修正手順を示します。すべて UI から自分で対応できます。

1. 認証情報の期限切れ・無効#

• 症状：実行が最初のノードで 401／認証失敗になり、接続テストも同様に失敗します。数週間動いていたのに突然始まることがよくあります。
• 原因：相手プラットフォームが認証情報を失効またはローテーションしたためです。トークンには寿命があります（例：Wish のアクセストークンは 30 日、OAuth ユーザートークンによっては数時間）。プラットフォーム側でシークレットを再生成しても変わります。
• 修正：①プラットフォームで新しい認証情報を取得（ディレクトリに正確な場所を記載）。②接続を開き、新しい値を貼って保存。③接続テストが通るまで実行。④障害中に発生したデッドレターをリプレイ。

2. Mapping の欠落・型の不一致#

• 症状：実行が中間のノードで失敗し、「フィールド X は必須」「未マッピングの SKU」、または型違いで値が拒否されます（数字の場所にテキスト、日付形式の不一致）。新しい SKU を含む新規注文が典型的な引き金です。
• 原因：Mapping が期待するソースフィールドがその伝票で空または欠落していた、両システムでフィールドの型の解釈が違う、またはチャネル SKU が OMS 製品と一度も紐付けられていない、のいずれかです。
• 修正：①失敗した実行を開き、どのノードのどのフィールドか確認。②未マッピング SKU は製品マッピングの保留リストで紐付け。③フィールド欠落／型違いは Flow（または接続）の Mapping を開き、正しいソースフィールドを対応させるか、デフォルト値／変換を追加。④ドライランで確認し、Flow を編集したら再公開して、デッドレターをリプレイ。

3. 相手プラットフォームのレート制限#

• 症状：実行ステータスが「retrying」になる、または 429／「too many requests」で失敗します。大量の手動取得の直後や、毎時 0 分に多くの Flow が同時発火すると悪化します。
• 原因：すべてのプラットフォームはアカウントごとに 1 分／1 時間あたりの API 呼び出し上限を設けています。コネクタはバックオフ付きで自動リトライします（それが「retrying」です）が、持続的なバーストでは上限を使い切ることがあります。
• 修正：①たまにの「retrying」は何もしなくて OK（通常は自動で成功します）。②繰り返す場合は接続／Flow スケジュールの取得頻度を下げる。③複数の Flow の時刻をずらし、同じプラットフォームに同分に集中させない。④バックログのリトライ中は手動取得を繰り返さない。

4. Webhook／コールバックの失敗#

• 症状：プッシュで届くはずのデータが来ません（追跡番号や履行確認が来ない、新規注文の通知が止まる）。一方で手動取得は正常です。ログに webhook 配信エラーが出ます。
• 原因：送信側プラットフォームが Docklify へ配信できなかった（一次的なネットワーク問題）、認証情報を変えた際にサブスクリプションが外れた、または接続を無効化→再有効化した際にコールバックが再登録されなかった、のいずれかです。
• 修正：①Integration → ログで webhook エラーと時刻を確認。すでに止まった短時間の集中なら対応不要。②接続をテスト。多くのプラットフォームではテスト成功時にコールバック登録が再検証されます。③それでもプッシュが来なければ、接続を無効化→再有効化してサブスクリプションを強制的に張り直す。④手動取得を 1 回行って漏れた分を補い、次の実イベントが届くか確認。

5. データ形式の問題#

• 症状：同じ接続で一部の伝票だけ失敗します。住所が無効で拒否される注文、形式の違う電話番号、解釈できない郵便番号、単位が混ざった重量などです。
• 原因：データそのもの（ソースプラットフォームやソース伝票に存在する形）が、受信側の形式ルールを満たしていません。Flow と認証情報は正常で、問題はその伝票です。
• 修正：①失敗した実行を開き、拒否された伝票とフィールドを確認（エラーに明記されています）。②ソースで直せるものはソースで修正（注文やプラットフォーム上の住所／電話を正す）。③同じプラットフォームから同じ癖が繰り返し来る場合は、Mapping で一度だけ処理：そのフィールドにデフォルト値、トリミング、変換を追加。④修正した伝票のデッドレターをリプレイ。