EventSyncとHubSpot間のデータ同期が失敗する場合の原因と解決手順を詳しく解説します。
同期エラーの確認方法
HubSpotとのデータ同期エラーを確認するには、管理画面の「HubSpot連携」メニューから「同期ログ」を開いてください。各同期操作の成功・失敗ステータスと、失敗した場合のエラーコードが記録されています。
最も多い同期エラーの原因はAPIキーの期限切れまたは権限不足です。HubSpot管理画面で発行したAPIキーまたはプライベートアプリのトークンが有効であることを確認し、必要なスコープ（crm.objects.contacts.write、crm.objects.deals.writeなど）が付与されているか確認してください。
HubSpot APIのレート制限（1秒あたり10リクエスト）に達した場合も同期エラーが発生します。大量のデータを一度に同期しようとすると429エラーが返され、同期処理が中断されます。この場合はバッチサイズを小さくするか、同期スケジュールを分散させてください。
よくある同期エラーとその対処
「Contact not found」エラーは、EventSyncが参照しようとしたHubSpotコンタクトが存在しない場合に発生します。コンタクトが削除されていたり、メールアドレスが変更されていたりすることが原因です。EventSyncの「コンタクト再マッチング」機能を使って、メールアドレスベースで再紐付けを試みてください。
「Property value not allowed」エラーは、HubSpotのカスタムプロパティに許可されていない値を書き込もうとした場合に発生します。HubSpotのプロパティ定義で許可している値の一覧と、EventSyncが送信しようとしているデータを照合して不一致を修正してください。
「Duplicate contact」エラーは、同一メールアドレスのコンタクトがHubSpot側で重複している場合に発生します。HubSpotの重複管理機能でコンタクトをマージしてから再同期を試みてください。
同期の再試行と手動同期
同期エラーが発生した場合、EventSyncは設定に応じて自動的に再試行を行います。デフォルトでは5分間隔で最大3回再試行します。再試行間隔と回数は「連携設定」画面でカスタマイズできます。
エラーが解消されない場合は、管理画面の「手動同期」ボタンから対象のデータを選択して個別に同期を実行してください。手動同期では、同期処理のリアルタイムログを確認しながら問題を特定することができます。
HubSpot APIのレート制限（10リクエスト/秒）を常時超えている場合は、同期設定の「バッチ処理の最適化」を有効にしてください。この設定により、複数の同期操作をまとめて効率的に処理し、APIコール数を削減できます。