HubSpot APIをご利用中に「400 Bad Request: Property value is not valid」というエラーに直面し、お困りではないでしょうか？ ご安心ください。このエラーはHubSpot API連携で非常によく発生するものであり、原因を特定しやすく、比較的簡単に解決できる問題です。
この記事では、Windowsユーザーの方向けに、このエラーの概要から、今すぐ試せる最速の解決策、そして恒久的な再発防止策までを、具体的かつ分かりやすく解説します。
目次
1. HubSpot API: 400 Bad Request: Property value is not valid とは？（概要と緊急度）
このエラーは、HubSpot APIに対して送信したデータに含まれるプロパティの値が、HubSpot側で定義されているそのプロパティのルールに合致していない場合に発生します。
具体的には、以下のような状況で発生します。
- 数値型のプロパティに文字列を送った。
- 日付型のプロパティに不正な形式の日付を送った。
- 選択肢（ドロップダウンやチェックボックス）のプロパティに、HubSpotに登録されていない選択肢の値を送った。
- 必須項目であるプロパティに値が送られていない。
緊急度
緊急度は高です。このエラーが発生している場合、データ連携が正常に行われていないことを意味します。しかし、原因が明確なため、適切な手順を踏めば迅速に解決することが可能です。落ち着いて対処しましょう。
2. 【最速】今すぐ試すべき解決策
このエラーの最も速い解決策は、エラーの原因となっているプロパティのHubSpot側の定義と、APIで送信している値とを比較し、不一致箇所を特定して修正することです。
解決策1：HubSpot管理画面でプロパティ定義を確認し、APIリクエストのペイロードと比較する
まず、エラーメッセージに記載されている（または推測される）プロパティについて、HubSpotの管理画面でその定義を確認します。そして、APIリクエストで実際に送っているJSONデータの内容と比較してみましょう。
以下の手順で確認を進めてください。
# HubSpot管理画面でのプロパティ定義確認手順
# 1. HubSpotアカウントにログインします。
# 2. ナビゲーションバーの「設定」（歯車アイコン）をクリックします。
# 3. 左サイドバーの「データ管理」->「オブジェクト」（例：コンタクト、会社、取引など）を選択します。
# エラーが発生しているAPIのエンドポイント（例: /crm/v3/objects/contacts であれば「コンタクト」）
# に対応するオブジェクトを選択してください。
# 4. 「プロパティ」タブをクリックし、APIエラーが出ているプロパティ名（例: my_custom_property）を検索します。
# 5. 該当プロパティをクリックし、「フィールドタイプ」や「オプション」の詳細を確認します。
# 特に注意して確認すべきポイント：
# ・フィールドタイプ：
# - 「単一行テキスト」以外の場合、送信する値の形式がHubSpotの定義と一致しているか確認します。
# - 例：「数値」であれば、数値以外の文字列を送っていないか。
# - 例：「日付ピッカー」であれば、ISO 8601形式（例: "2023-10-27T10:00:00.000Z"）など、
# HubSpotが要求する正確な日付時刻フォーマットで送っているか。
# ・ドロップダウン選択、複数チェックボックス、ラジオ選択の場合：
# - 「オプション」セクションを展開し、「内部値」を確認します。
# - APIで送信する値は、画面に表示される「ラベル」ではなく、この「内部値」と完全に一致している必要があります。
# - 大文字・小文字、スペースの有無、全角・半角の違いも厳密にチェックしてください。
# ・「必須項目」のチェックボックス：
# - このプロパティが必須として定義されている場合、APIリクエストで必ず値が送信されているか確認します。
# 値が不足していると、このエラーが発生することがあります。
# --- APIリクエストのJSONペイロード確認例 (PowerShellを使用) ---
# 以下は、APIリクエストを生成しているアプリケーションやスクリプトから
# 送信されるJSONペイロードをデバッグするための一般的なアプローチです。
# 実際のエラー修正は、API呼び出しを行っているコードを修正することになります。
# 仮に、HubSpotに送信しようとしているJSONデータが以下のような形式だとします。
$examplePayload = @{
properties = @{
firstname = "HubSpot"
lastname = "User"
email = "user@example.com"
# ★★★ ここがエラーの原因となっているプロパティの可能性があります ★★★
# 例: HubSpot側で「数値型」と定義されているが、"Invalid Value" という文字列を送っているケース
my_custom_number_property = "Invalid Value"
# 例: HubSpot側で「選択リスト」と定義されており、「内部値」が "OptionA" のみ許可されているが、
# "option a" (小文字) を送っているケース
my_custom_picklist_property = "option a"
}
} | ConvertTo-Json -Depth 5 -Compress
Write-Host "--- APIで送信していると想定されるJSONペイロード ---"
Write-Host $examplePayload
# APIリクエストを送信しているコード（PowerShellスクリプト、C#, Pythonなど）を確認し、
# 実際にHubSpotに送信されている「my_custom_number_property」や
# 「my_custom_picklist_property」などの値が、
# HubSpot管理画面で確認したプロパティの定義と完全に一致するように修正してください。
# Tip: APIテストツール（Postman, Insomniaなど）を使用している場合は、
# そのツールで送信しているRequest Body (JSON) の内容を直接確認・修正してください。
HubSpotの定義とAPIリクエストのペイロードを注意深く比較することで、多くの場合はエラーの原因となっている不一致を特定し、修正することができます。
3. HubSpot API: 400 Bad Request: Property value is not valid が発生する主要な原因（複数）
「Property value is not valid」エラーは、主に以下のいずれかの原因で発生します。
原因1: データ型の不一致
- 例: HubSpotのプロパティが「数値型」として定義されているにも関わらず、APIリクエストで「”abc”」のような文字列を送信した場合。
- 例: HubSpotのプロパティが「日付ピッカー」として定義されているにも関わらず、APIリクエストで「”2023/10/27″」のようなHubSpotが認識しない日付形式を送信した場合（多くの場合、ISO 8601形式が求められます）。
原因2: 列挙値（選択リスト）の不一致
- 例: HubSpotの「ドロップダウン選択」プロパティに「Option A」「Option B」という内部値の選択肢しかないのに、APIリクエストで「Option C」や「option a」（大文字・小文字違い）を送信した場合。
- 注意: 多くのユーザーが画面上の「ラベル」とAPIで送信する「内部値」を混同しがちです。APIでは必ず「内部値」を使用し、大文字・小文字、スペースなども完全に一致させる必要があります。
原因3: 値の範囲外または形式の不備
- 例: 数値プロパティに、定義された最大値や最小値を超える値を送信した場合。
- 例: URLプロパティに、有効なURL形式ではない文字列を送信した場合。
- 例: 電話番号プロパティに、無効な電話番号形式を送信した場合。
原因4: 必須プロパティの欠如
- HubSpotで「必須項目」として定義されているプロパティに、APIリクエストで値が全く送信されていない場合も、このエラーが発生することがあります。
4. HubSpot APIで恒久的に再発を防ぐには
一度解決しても、システムの変更やプロパティの追加などで同様のエラーが再発しないよう、以下の対策を検討することをおすすめします。
1. 厳格なデータバリデーションの実装
APIを呼び出す側のアプリケーション（スクリプト、連携ツールなど）で、HubSpotにデータを送信する前に、プロパティ値のバリデーション（検証）ロジックを実装しましょう。これにより、不正なデータがHubSpotに到達する前に検出・修正できます。
- HubSpotプロパティ定義の同期: 可能であれば、HubSpotのAPIを使ってプロパティ定義（データ型、選択肢、必須フラグなど）を動的に取得し、それを基にバリデーションを行う仕組みを構築すると、手動での更新漏れを防げます。
2. HubSpotプロパティ定義の一元管理と共有
HubSpotのカスタムプロパティが追加・変更された際には、API連携に関わる全ての開発者や運用担当者に情報が確実に共有される仕組みを作りましょう。
- ドキュメント化: プロパティの定義（特に内部値や許容フォーマット）を詳細にドキュメント化し、常に最新の状態を保つ。
- 変更管理プロセス: プロパティの追加・変更は、必ずAPI連携への影響を考慮した上で、関係者へのレビューと承認を経てから行う運用を徹底する。
3. APIエラーロギングと監視の強化
エラーが発生した際に迅速に検知し、原因を特定できるように、ロギングと監視の体制を強化しましょう。
- 詳細なエラーログ: APIエラー発生時には、どのようなプロパティで、どんな値が不正だったのか、HubSpotから返される詳細なエラーメッセージを正確にログに記録する。
- アラート設定: 400 Bad Requestなどのエラーが一定数発生した場合に、担当者に自動的に通知が届くようなアラートシステムを導入する。
4. テスト環境での十分な検証
新しいAPI連携を構築したり、既存の連携を更新したりする際には、必ず本番環境にデプロイする前に、テスト環境で十分な検証を行いましょう。様々なデータパターンを試すことで、潜在的な問題を早期に発見できます。
これらの対策を実施することで、HubSpot APIとの連携がより安定し、スムーズなデータフローを維持できるようになります。