EventSync APIが返す主要なHTTPエラーコードの意味と、それぞれに対する具体的な対処法をまとめました。
4xx クライアントエラー
400 Bad Requestは、リクエストの形式が不正な場合に返されます。リクエストボディのJSONが正しく整形されているか、必須パラメータがすべて含まれているか、データ型が正しいかを確認してください。エラーレスポンスの「details」フィールドに具体的な不正箇所が記載されています。
401 Unauthorizedは、認証情報が無効または欠落している場合に返されます。AuthorizationヘッダーにBearerトークンが正しく設定されているか確認してください。トークンの有効期限が切れている場合は、再認証して新しいトークンを取得してください。403 Forbiddenは、認証は成功しているものの、操作に必要な権限がない場合に返されます。APIキーに付与されているスコープを確認し、必要な権限を追加してください。
404 Not Foundは、指定したリソース（イベント、予約など）が存在しない場合に返されます。IDやスラッグが正しいかを再確認してください。削除済みのリソースを参照している可能性もあるため、管理画面で対象リソースの存在を確認してください。
429 レート制限エラーと5xxサーバーエラー
429 Too Many Requestsは、HubSpot APIのレート制限（1秒あたり10リクエスト）を超えた場合に返されます。レスポンスヘッダーの「Retry-After」フィールドに、次のリクエストまで待機すべき秒数が示されています。実装側でこのヘッダーを読み取り、指定秒数後に自動再試行するロジックを組み込んでください。
大量のAPIコールが必要な処理では、リクエストをキューに積んで1秒あたり10件以下に制限するスロットリング処理を実装することを強く推奨します。バースト的なリクエストを避けるため、コール間に100ミリ秒のインターバルを設けることも有効です。
500 Internal Server Errorは、サーバー側の予期しないエラーを示します。一時的な問題であることが多いため、指数バックオフ（1秒→2秒→4秒）で数回再試行してください。継続して発生する場合は、リクエストのIDをサポートに報告してください。503 Service Unavailableはメンテナンス中または過負荷状態を示します。ステータスページを確認し、復旧まで待機してください。
エラーハンドリングのベストプラクティス
堅牢なAPIクライアントを実装するには、すべてのエラーレスポンスを適切にハンドリングするコードが必要です。特に429と503エラーに対しては、自動再試行ロジックを必ず実装してください。再試行回数の上限（推奨: 3〜5回）と最大待機時間（推奨: 32秒）を設定し、無限ループを防いでください。
本番環境でのデバッグを容易にするため、すべてのAPIリクエストとレスポンスをログに記録することをお勧めします。ただし、個人情報や認証トークンはログに含めないようにしてください。リクエストIDを各コールに付与しておくと、サポートへの問い合わせ時に迅速に状況を伝えられます。
Webhookを受信する実装では、受信後に速やかに200レスポンスを返し、処理は非同期で行うようにしてください。処理に時間がかかる場合にタイムアウトが発生し、EventSyncが同じWebhookを複数回送信する原因となります。べき等性を考慮した実装で、重複受信を安全に処理できるようにしてください。