最終更新日: 2025年9月12日
// translate-ignore ‘HubSpotのAPIを使用して開発する際の一般的なAPIエラーを処理する方法を説明します。’; 特に明記されていない限り、大半のHubSpotエンドポイントは、リクエストが正常に完了すると200 OKレスポンスを返します。他のステータスコードを返すエンドポイントについては、エンドポイントのドキュメントに、どのレスポンスが返されるかが明記されています。 さらに、HubSpotには、複数のAPIに共通する次のようなエラーレスポンスがあります。
  • 207 Multi-Status：複数の異なるステータス（エラーと成功など）がある場合、このエラーレスポンスが返されます。こうした状況が発生するのは、オブジェクトAPIバッチ作成エンドポイントでマルチステータスのエラー処理が有効にされている場合です。
  • 401 Unauthorized：APIに渡された認証情報が無効である場合、このエラーレスポンスが返されます。APIリクエストの認証について詳しくは、認証の概要をご確認ください。
  • 403 Forbidden：APIに渡された認証対象にその特定のURLに対するアクセス権限が付与されていない場合、このエラーレスポンスが返されます。例えば、コンテンツのアクセス権限しか付与されていないOAuthトークンによって取引API（コンタクトアクセス権限が必要）にアクセスしようとすると、403が返されます。APIキーまたは非公開アプリに必要な権限が付与されていることを確認した場合は、HubSpotのサポートチームにお問い合わせください。
  • 423 Locked：大量のデータを同期しようとした場合（ごく短期間のうちに数千の会社レコードを更新または挿入した場合など）に返されます。ロック状態は2秒間続くため、423エラーが発生した場合は、次のAPIリクエストを実行するまでに少なくとも2秒の遅延を含める必要があります。
  • 429 Too many requests：アカウントまたはアプリが、該当するAPIレート制限を超えている場合、このエラーレスポンスが返されます。レート制限内で作業するための推奨事項については、こちらをご確認ください。
  • 477 Migration in Progress：HubSpotアカウントが現在データのホスティング場所間で移行中の場合、このエラーレスポンスが返されます。HubSpotは、リクエストを再試行できるまでの秒数を示すRetry-Afterレスポンスヘッダーを返します（通常は最大24時間）。
  • 502/504 timeouts：HubSpotの処理制限に達している場合、このエラーレスポンスが返されます。これらの制限は、単一のクライアントによってパフォーマンスの低下が招かれないようにするために設定されています。長時間にわたって大量のリクエストを送信すると、これらのタイムアウトレスポンスが表示されます。これらのレスポンスのいずれかが表示されたら、数秒間リクエストを一時停止してから再試行してください。
  • 503 service temporarily unavailable：HubSpotが一時的に利用できない場合、このエラーレスポンスが返されます。このレスポンスが表示されたら、数秒間リクエストを一時停止してから再試行してください。
  • 521 web server is down：HubSpotのサーバーがダウンしている場合、このエラーレスポンスが返されます。これは一時的な問題であるはずです。このレスポンスが表示されたら、数秒間リクエストを一時停止してから再試行してください。
  • 522 connnection timed out：HubSpotとアプリケーション間の接続がタイムアウトになった場合、このエラーレスポンスが返されます。このレスポンスが表示された場合は、HubSpotのサポートチームにお問い合わせください。
  • 523 origin is unreachable：HubSpotがアプリケーションに接続できない場合、このエラーレスポンスが返されます。このレスポンスが表示されたら、数秒間リクエストを一時停止してから再試行してください。
  • 524 timeout：100秒以内に応答が受信されない場合、このエラーレスポンスが返されます。大規模なデータクエリーなどによってHubSpotのサーバーが過負荷状態になっていると、このエラーが発生する可能性があります。このレスポンスが表示されたら、数秒間リクエストを一時停止してから再試行してください。
  • 525/526 SSL issues：SSL証明書が無効である、またはSSLハンドシェイクが失敗した場合に、このエラーレスポンスが返されます。このレスポンスが表示された場合は、HubSpotのサポートチームにお問い合わせください。
上記の全般的なエラーを除いて、HubSpotのエラーレスポンスは基本的に読みやすく記述されています。ほとんどのエンドポイントから、エラーコードではなく、エラーに関する詳細を記載したJSON形式のレスポンスが返されます。
  • CRMオブジェクトAPIの場合、エラーレスポンスには詳細なmessage、code、contextのフィールドが含まれ、リクエストに含まれていない必須プロパティーやリクエスト内に不正な形式のプロパティーが含まれる問題について追加情報が提供されます。
  • エンドポイント固有のエラーの詳細は、該当するエンドポイントのドキュメントページに記載されています。
// Structure of an example error from HubSpot
{
  "status": "error",
  "message": "This will be a human readable message with details about the error.",
  "errors": [
    {
      "message": "discount was not a valid number",
      "code": "INVALID_INTEGER",
      "context": {
        "propertyName": ["discount"]
      }
    }
  ],
  "category": "VALIDATION_ERROR",
  "correlationId": "a43683b0-5717-4ceb-80b4-104d02915d8c"
}

​
マルチステータスエラー

オブジェクトAPI’バッチ作成エンドポイントでは、部分的なエラーが含まれるマルチステータスのレスポンスを有効にすることができます。つまり、どのレコードが作成され、どのレコードが作成されなかったかがレスポンスで示されます。そのためには、リクエスト内の入力ごとに一意のobjectWriteTraceId値を含めます。objectWriteTraceIdには、任意の一意の文字列を指定できます。 例えば、チケットの作成リクエストは以下のようになります。 
///Example request to POST crm/v3/objects/tickets/batch/create
{
  "inputs": [
    {
      "objectWriteTraceId": "549b1c2a9350",
      "properties": {
        "hs_pipeline_stage": "1"
      },
      "objectWriteTraceId": "549b1c2a9351",
      "properties": {
        "missing": "1"
      }
    }
  ]
}
レスポンスではステータスがグループ化されるため、どのチケットの作成が成功し、どのチケットの作成が失敗したかを確認できます。上記のリクエストに対するレスポンスは以下のようになります。 
///Example response
{
  "status": "COMPLETE",
  "results": [
    {
      "id": "1145814089",
      "properties": {
        "createdate": "2024-08-15T17:09:13.648Z",
        "hs_helpdesk_sort_timestamp": "2024-08-15T17:09:13.648Z",
        "hs_last_message_from_visitor": "false",
        "hs_lastmodifieddate": "2024-08-15T17:09:13.648Z",
        "hs_object_id": "1145814089",
        "hs_object_source": "API",
        "hs_object_source_label": "INTERNAL_PROCESSING",
        "hs_pipeline": "0",
        "hs_pipeline_stage": "1",
        "hs_ticket_id": "1145814089"
      },
      "createdAt": "2024-08-15T17:09:13.648Z",
      "updatedAt": "2024-08-15T17:09:13.648Z",
      "archived": false
    }
  ],
  "numErrors": 1,
  "errors": [
    {
      "status": "error",
      "category": "VALIDATION_ERROR",
      "message": "Property values were not valid: [{\"isValid\":false,\"message\":\"Property \\\"missing\\\" does not exist\",\"error\":\"PROPERTY_DOESNT_EXIST\",\"name\":\"missing\",\"localizedErrorMessage\":\"Property \\\"missing\\\" does not exist\",\"portalId\":891936587}]",
      "context": {
        "objectWriteTraceId": ["549b1c2a9351"]
      }
    }
  ],
  "startedAt": "2024-08-15T17:09:13.610Z",
  "completedAt": "2024-08-15T17:09:13.910Z"
}

​
再試行

アプリまたは連携で、HubSpotが呼び出すAPIエンドポイント（Webhook配信登録など）が提供されている場合、エンドポイントからどのエラーがスローされても、HubSpotはリクエストを再試行します。

​
Webhook

貴社のサービスに通知の処理の問題が発生した場合はいつでも、HubSpotは最大10回、失敗した通知の再送を試みます。 HubSpotが再試行するのは以下の場合です。
  • 接続失敗: 指定されたWebhook URLへのHTTP接続をHubSpotが開始できない場合。
  • タイムアウト: 一括通知に対するレスポンスが貴社のサービスから5秒以内に返されない場合。
  • エラーコード: 貴社のサービスがHTTPステータスコード（4xxまたは5xx）で応答した場合。
4xxのレスポンス ステータス コードを受信した後、ワークフローは再試行されません。このルールの1つの例外は429レート制限エラーです。429レスポンスを受け取った後、ワークフローは自動的に再試行されます。また、Retry-Afterヘッダーが存在する場合は、このヘッダーでの指定に従います。Retry-After値はミリ秒単位であることに注意してください。 通知の送信は最大で10回再試行されます。再試行は、24時間にわたりリクエストの送信間隔を変えながら実行されます。失敗が同時に多発した場合の再試行時刻が完全に同じにならないように、個々の通知にある程度のばらつきが確保されます。

​
カスタムコードのワークフローアクション

ワークフローでカスタム コード アクションを作成する場合、レート制限エラーや、axiosあるいは@hubspot/api-clientから返された429または5XXエラーが原因でアクションでのAPI呼び出しが失敗すると、HubSpotはエラー発生の1分後から最大3日間、そのアクションを再試行します。以降のアクション再試行が失敗した場合、徐々に間隔を延ばしてアクションが再試行されます。再試行の間隔は最大で8時間です。