HubSpot API: 400 Bad Request: Property value is not valid でハマったあなたへ！カスタムプロパティ値検証エラーの解決策

HubSpot APIを使ってデータ連携していると、突然 HubSpot API: 400 Bad Request: Property value is not valid というエラーに遭遇すること、ありますよね？「あれ、昨日まで動いてたのに…」「値はちゃんと渡してるはずなのに…」と頭を抱え、デバッグに時間を取られる。その気持ち、痛いほどよく分かります。

結論から言うと、このエラーの主な原因は、HubSpot側で定義されているプロパティの型や許容される値の形式と、APIで送信しているデータが一致しないことにあります。そして、解決策はズバリ、HubSpotのプロパティ定義を正確に確認し、それに合わせて送信データを見直すことです。さあ、一緒にこの厄介なエラーを解決していきましょう！

1. エラーコード HubSpot API: 400 Bad Request: Property value is not valid とは？

このエラーは、API連携においてよく見られる 400 Bad Request の一種です。400 Bad Request は、一般的に「クライアント（あなた）から送信されたリクエストが不正である」ことを示します。そして、今回の場合に付随する Property value is not valid というメッセージが、その不正の内容を具体的に教えてくれています。

つまり、あなたがHubSpotの特定のオブジェクト（コンタクト、会社、取引など）に対してデータを更新・作成しようとした際、送信したプロパティ（項目）の値が、HubSpot側で設定されているそのプロパティの「ルール」に合致しないために発生している、ということですね。

2. 最速の解決策 3選

では、早速このエラーを解決するための具体的なアプローチを見ていきましょう。真っ先に確認すべきは以下の3点です。

2-1. HubSpotのプロパティ定義を正確に確認する

これが最も重要かつ最初のステップです。HubSpotの管理画面から、エラーが発生しているプロパティの定義を一つずつ確認してください。

• プロパティの型： テキスト、数値、日付、ドロップダウン、ラジオボタン、チェックボックス、複数チェックボックスなど、さまざまな型があります。APIで送信している値は、その型に沿っていますか？
  • 例: 数値型なのに文字列（”123″）を送っていませんか？
  • 例: 日付型なのにフォーマットが間違っていませんか？ (YYYY-MM-DD, UNIX_TIMESTAMP などHubSpotが期待する形式)
• 列挙値（ドロップダウン、ラジオボタン、複数チェックボックス）： これらのプロパティには、あらかじめ設定された選択肢しか入力できません。特に注意すべきは「内部名 (Internal Value)」です。
  • APIで送るべきは、表示名（ラベル）ではなく、内部名 であることがほとんどです。HubSpotのプロパティ設定画面で、各オプションの「内部名」を確認してください。
  • もし存在しない選択肢の値を送っている場合もこのエラーになります。
• データフォーマット：
  • 電話番号やURLなど、特定のフォーマットが求められる場合があります。
  • 複数選択プロパティは、多くの場合、値の配列（例: ["option1", "option2"]）として送信する必要があります。

2-2. APIで送信するデータ形式をHubSpotの定義に合わせる

HubSpotのプロパティ定義を確認したら、次はあなたのアプリケーションが実際に送信しているAPIリクエストのペイロードを見直しましょう。

• ドロップダウン/ラジオボタン： HubSpotで設定されている内部名と全く同じ文字列を送信していますか？大文字・小文字、全角・半角、スペースなども厳密に一致させる必要があります。
• 数値型： 数値として送信していますか？クォーテーションで囲まれて文字列になっていませんか？
• 日付型： HubSpotが求める日付フォーマット（ISO 8601形式など）に変換されていますか？タイムゾーンの考慮も必要になる場合があります。
• チェックボックス： true / false などのブール値、またはHubSpotが指定する特定の文字列（例: "true" / "false"）で送信していますか？

2-3. APIリクエストのペイロードをデバッグログなどで確認する

アプリケーション側で生成されたAPIリクエストの最終的なJSONペイロードやフォームデータを、デバッグログやネットワークトラフィックのキャプチャツールなどで確認してください。

• 実際にHubSpotに送信されているデータが、あなたの想定通りの値やフォーマットになっているか、目で見て確認することが重要です。
• プログラミング言語によっては、オブジェクトからJSONへのシリアライズ時に意図しない形式に変換されることがあります。

3. エラーの根本原因と再発防止策

一時的にエラーを解決できたとしても、同じ問題が再発しないように、根本原因を理解し対策を講じることがベテランエンジニアへの道です。

3-1. よくある根本原因

• HubSpot側のプロパティ定義の変更： HubSpotの利用者がプロパティの型やオプションを変更したが、API連携側のシステムがその変更に対応できていない。
• 開発時の認識齟齬： プロパティの正しい型や許容値を開発者が誤って認識していた、または確認を怠った。
• データ変換ロジックの不備： 連携元システムとHubSpotの間でデータを変換するロジックにバグや考慮漏れがあった。
• 環境の違い： 開発環境やステージング環境と本番環境で、HubSpotのプロパティ定義が異なっている。

3-2. 再発防止策

• プロパティ定義の一元管理と共有： HubSpotのプロパティ定義を開発チーム内でドキュメント化し、変更があった際には必ず共有・通知するプロセスを確立しましょう。
• 強力なバリデーションの実装： APIリクエストを送信する前に、アプリケーション側でHubSpotのプロパティ定義に合わせたバリデーションロジックを実装し、不正なデータを送信しないように防ぐ。
• テスト環境での厳密な確認： 新しいプロパティの追加や既存プロパティの変更があった場合、本番デプロイ前にテスト環境でAPI連携が正常に動作するかを徹底的にテストする。
• 詳細なエラーログの出力： エラー発生時に、どのプロパティの、どの値が問題だったのかを特定できるような詳細なログをアプリケーションから出力する仕組みを作る。
• Webhookや変更通知の活用： HubSpotのプロパティ定義が変更された際に、Webhookなどで通知を受け取り、自動的にAPI連携側で更新できる仕組みを検討する。

4. まとめ

HubSpot API: 400 Bad Request: Property value is not valid エラーは、一見すると厄介ですが、その原因はシンプルです。HubSpotのプロパティ定義と、あなたが送る値がズレている。これだけを覚えておけば大丈夫です。

今回の記事で紹介した「HubSpotのプロパティ定義確認」「送信データの見直し」「ペイロードのデバッグ」の3つのステップを順に踏んでいけば、ほとんどの場合、問題は解決するはずです。

“`