Portfolioこの記事について
ネットワーク障害やAPI制限により、同期が失敗することは避けられません。そのため、エラー時のリカバリー方法を設計しておく必要があります。エラーパターンと対処方法を解説します。
同期失敗の種類
エラーパターンの分類
| パターン | 原因 | 発生頻度 | 緊急度 |
|---|---|---|---|
| 接続エラー | ネットワーク障害、API停止 | 低い | 高い |
| タイムアウト | 処理遅延、過負荷 | やや低い | 中 |
| 認証エラー | トークン期限切れ、権限不足 | 低い | 高い |
| レート制限 | API呼び出し制限超過 | 中程度 | 低い |
| データエラー | フォーマット不正、必須項目不足 | 中程度 | 中 |
| 重複エラー | 既存データとの衝突 | やや高い | 低い |
接続エラー
原因ネットワーク障害、API停止
発生頻度低い
緊急度高い
タイムアウト
原因処理遅延、過負荷
発生頻度やや低い
緊急度中
認証エラー
原因トークン期限切れ、権限不足
発生頻度低い
緊急度高い
レート制限
原因API呼び出し制限超過
発生頻度中程度
緊急度低い
データエラー
原因フォーマット不正、必須項目不足
発生頻度中程度
緊急度中
重複エラー
原因既存データとの衝突
発生頻度やや高い
緊急度低い
エラーパターンと対策
パターン1: POS API接続エラー
| 項目 | 内容 |
|---|---|
| 状況 | POSシステムへのAPI接続が失敗 |
| 原因例 | POSサーバーダウン、ネットワーク障害、メンテナンス中 |
状況
内容POSシステムへのAPI接続が失敗
原因例
内容POSサーバーダウン、ネットワーク障害、メンテナンス中
接続エラー時の対応方針
Shopify登録は成功させる
メインの登録処理は維持
POS同期をスキップ
エラーログを記録し、管理者に通知
後で再同期
手動または自動で再同期を実行
顧客への影響: オンラインでは通常通り利用可能。店舗利用は「少しお待ちください」と案内
パターン2: データ形式エラー
| 項目 | 内容 |
|---|---|
| 状況 | POS APIがデータフォーマットエラーを返す |
| 原因例 | 必須項目が空、電話番号の形式が不正、住所が長すぎる |
状況
内容POS APIがデータフォーマットエラーを返す
原因例
内容必須項目が空、電話番号の形式が不正、住所が長すぎる
データエラー時の対応方針
エラー詳細をログに記録
どのフィールドが問題かを特定
自動修正を試行
可能なら修正して再試行 / 無理なら管理者に通知
| 自動修正の例 | 処理内容 |
|---|---|
| 電話番号 | ハイフンを除去 |
| 住所 | 文字数制限に合わせてカット |
| 空フィールド | デフォルト値を設定 |
電話番号
処理内容ハイフンを除去
住所
処理内容文字数制限に合わせてカット
空フィールド
処理内容デフォルト値を設定
パターン3: 重複エラー
| 項目 | 内容 |
|---|---|
| 状況 | 「このメールアドレスは既に登録されています」エラー |
| 原因 | 既存の店舗会員がオンラインで新規登録、または同期タイミングのずれで二重登録 |
状況
内容「このメールアドレスは既に登録されています」エラー
原因
内容既存の店舗会員がオンラインで新規登録、または同期タイミングのずれで二重登録
重複エラー時の対応方針
既存顧客との紐付けを試みる
メールアドレスで既存顧客を検索
紐付け結果
成功 → 既存顧客の会員番号を更新 / 失敗 → 重複の可能性を記録
管理者が確認・マージ
ポイント残高の合算、購買履歴の統合、古い方のレコードを無効化
リカバリーの仕組み
自動リトライ
| 試行 | 待機時間 | 次のアクション |
|---|---|---|
| 1回目失敗 | 2秒 | 再試行 |
| 2回目失敗 | 4秒 | 再試行 |
| 3回目失敗 | 8秒 | 再試行 |
| 4回目失敗 | - | 諦めてエラー記録 |
1回目失敗
待機時間2秒
次のアクション再試行
2回目失敗
待機時間4秒
次のアクション再試行
3回目失敗
待機時間8秒
次のアクション再試行
4回目失敗
待機時間-
次のアクション諦めてエラー記録
エクスポネンシャルバックオフ: 待ち時間を2倍ずつ増やすことで、サーバーへの負荷を軽減
| エラー種別 | リトライ | 理由 |
|---|---|---|
| 接続エラー | する | 一時的な障害の可能性 |
| タイムアウト | する | 一時的な過負荷の可能性 |
| 認証エラー | しない | リトライしても同じ結果 |
| データ形式エラー | しない | データ修正が必要 |
| 重複エラー | しない | 別の対応が必要 |
接続エラー
リトライする
理由一時的な障害の可能性
タイムアウト
リトライする
理由一時的な過負荷の可能性
認証エラー
リトライしない
理由リトライしても同じ結果
データ形式エラー
リトライしない
理由データ修正が必要
重複エラー
リトライしない
理由別の対応が必要
未同期データの管理
| 顧客ID | Shopify | POS同期 | CRM同期 | 備考 |
|---|---|---|---|---|
| 12345 | 成功 | 成功 | 成功 | - |
| 12346 | 成功 | 失敗 | 成功 | 要再同期 |
| 12347 | 成功 | 成功 | スキップ | - |
12345
Shopify成功
POS同期成功
CRM同期成功
備考-
12346
Shopify成功
POS同期失敗
CRM同期成功
備考要再同期
12347
Shopify成功
POS同期成功
CRM同期スキップ
備考-
管理画面での確認方法:
- 「POS同期失敗」でフィルタリング
- エラー内容の確認
- 「再同期」ボタンで再試行
管理者向けツール
同期ステータス確認
| 項目 | 件数 | アクション |
|---|---|---|
| 同期済み | 1,234 件 | - |
| 未同期（POS） | 5 件 | 詳細を見る |
| 未同期（CRM） | 2 件 | 詳細を見る |
同期済み
件数1,234 件
アクション-
未同期（POS）
件数5 件
アクション詳細を見る
未同期（CRM）
件数2 件
アクション詳細を見る
| 顧客ID | 氏名 | エラー種別 | 発生時刻 |
|---|---|---|---|
| 12346 | 山田太郎 | POS接続エラー | 10:30 |
| 12350 | 鈴木花子 | データ形式エラー | 10:25 |
12346
氏名山田太郎
エラー種別POS接続エラー
発生時刻10:30
12350
氏名鈴木花子
エラー種別データ形式エラー
発生時刻10:25
操作: 「未同期を一括再同期」ボタンで対象を一括処理
再同期機能
対象選択
未同期の顧客を一覧から選択（個別または一括）
再同期実行
「再同期」ボタンで同期処理を再実行
結果確認
成功/失敗の結果を確認
継続対応
まだ失敗する場合はエラー詳細を確認して対応
エラーログの設計
記録すべき情報
| 項目 | 内容 | 用途 |
|---|---|---|
| タイムスタンプ | エラー発生日時 | 時系列分析 |
| 顧客ID | 対象の顧客 | 追跡と再試行 |
| 同期先 | POS/CRM等 | 障害箇所の特定 |
| エラー種別 | 接続/認証/データ等 | 対応方法の判断 |
| エラー詳細 | APIレスポンス等 | 原因調査 |
| リトライ回数 | 何回試したか | エスカレーション判断 |
タイムスタンプ
内容エラー発生日時
用途時系列分析
顧客ID
内容対象の顧客
用途追跡と再試行
同期先
内容POS/CRM等
用途障害箇所の特定
エラー種別
内容接続/認証/データ等
用途対応方法の判断
エラー詳細
内容APIレスポンス等
用途原因調査
リトライ回数
内容何回試したか
用途エスカレーション判断
ログの例
| フィールド | 値 | 説明 |
|---|---|---|
| timestamp | 2024-01-15T10:30:00Z | エラー発生日時 |
| level | error | ログレベル |
| event | pos_sync_failed | イベント種別 |
| customer_id | 12346 | 対象の顧客ID |
| customer_email | yamada@example.com | 顧客メールアドレス |
| sync_target | pos | 同期先システム |
| error_type | connection_error | エラー種別 |
| error_message | Connection timed out after 15000ms | エラー詳細 |
| retry_count | 4 | リトライ回数 |
| will_retry | false | 追加リトライの有無 |
| shopify_sync | success | Shopify同期結果 |
| crm_sync | success | CRM同期結果 |
timestamp
値2024-01-15T10:30:00Z
説明エラー発生日時
level
値error
説明ログレベル
event
値pos_sync_failed
説明イベント種別
customer_id
値12346
説明対象の顧客ID
customer_email
値yamada@example.com
説明顧客メールアドレス
sync_target
値pos
説明同期先システム
error_type
値connection_error
説明エラー種別
error_message
値Connection timed out after 15000ms
説明エラー詳細
retry_count
値4
説明リトライ回数
will_retry
値false
説明追加リトライの有無
shopify_sync
値success
説明Shopify同期結果
crm_sync
値success
説明CRM同期結果
監視とアラート
アラート条件
| 条件 | アラートレベル | 通知先 |
|---|---|---|
| POS同期失敗が5件/時を超過 | 警告 | Slack通知 |
| POS同期が10分以上連続失敗 | 緊急 | 電話・メール |
| 未同期データが100件を超過 | 警告 | 日次レポート |
| 認証エラーが発生 | 緊急 | 即時通知 |
POS同期失敗が5件/時を超過
アラートレベル警告
通知先Slack通知
POS同期が10分以上連続失敗
アラートレベル緊急
通知先電話・メール
未同期データが100件を超過
アラートレベル警告
通知先日次レポート
認証エラーが発生
アラートレベル緊急
通知先即時通知
ダッシュボード
| 同期先 | 成功率（過去24時間） |
|---|---|
| POS | 99.2% |
| CRM | 99.8% |
| 全体 | 99.5% |
POS
成功率（過去24時間）99.2%
CRM
成功率（過去24時間）99.8%
全体
成功率（過去24時間）99.5%
エラー推移: 時系列でエラー発生件数をグラフ表示し、傾向を把握
直近のエラー: 10:30 接続エラー 1件 → 自動リトライで解消
この設計がもたらす効果
可用性
- 一部のエラーがあっても全体のサービスは継続
- 自動リトライで一時的な障害から回復
- 手動対応が必要な場合も迅速に把握
運用効率
- エラーの自動検知と通知
- 管理画面から簡単に再同期
- 原因調査のためのログが充実
顧客体験
- エラーがあっても基本的なサービスは継続
- 問題解決までの時間を最小化
- 透明性のある状況報告が可能