Handling errors

特に明記されていない限り、大半のHubSpotエンドポイントは、リクエストが正常に完了すると200 OKレスポンスを返します。他のステータスコードを返すエンドポイントについては、エンドポイントのドキュメントに、どのレスポンスが返されるかが明記されています。

さらに、HubSpotには、複数のAPIに共通する次のようなエラーレスポンスがあります。

  • 401 Unauthorized：APIに渡された認証情報が無効な場合、このエラーレスポンスが返されます。APIリクエストの認証については、認証の概要（英語）を参照してください。
  • 403 Forbidden：APIに渡された認証対象にその特定のURLに対するアクセス権限が付与されていない場合、このエラーレスポンスが返されます。例えば、コンテンツのアクセス権限しか付与されていないOAuthトークンによって取引API（コンタクトアクセス権限が必要）にアクセスしようとすると、403が返されます。APIキーまたは非公開アプリに対する権限が必要であることを確認した場合は、HubSpotのサポートチームにお問い合わせください。 
  • 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 connection timed out：HubSpotとアプリケーション間の接続がタイムアウトになった場合、このエラーレスポンスが返されます。このレスポンスが表示された場合は、HubSpotのサポートチームにお問い合わせください。 
  • 523 origin is unreachable：HubSpotがアプリケーションに接続できない場合、このエラーレスポンスが返されます。このレスポンスが表示されたら、数秒間リクエストを一時停止してから再試行してください。 
  • 524 timeout：100秒以内に応答が受信されない場合、このエラーレスポンスが返されます。大規模なデータクエリーなどによってHubSpotのサーバーが過負荷状態になっていると、このエラーが発生する可能性があります。このレスポンスが表示されたら、数秒間リクエストを一時停止してから再試行してください。
  • 525/526 SSL issues：SSL証明書が無効であるか、またはSSLハンドシェイクが失敗した場合、このエラーレスポンスが返されます。このレスポンスが表示された場合は、HubSpotのサポートチームにお問い合わせください。 

上記の全般的なエラーを除いて、HubSpotのエラーレスポンスは基本的に読みやすく記述されています。ほとんどのエンドポイントから、エラーコードではなく、エラーに関する詳細を記載したJSON形式のレスポンスが返されます。エンドポイント固有のエラーの詳細は、該当するエンドポイントのドキュメントページに記載されています。

注：以下のレスポンスの例に示されている全てのフィールドは、エラー解析時には任意指定として扱ってください。APIごとに使用する具体的なフィールドは異なるため、エラー解析では、レスポンスに特定のフィールドが欠落していても許容する必要があります。

// Structure of an example error from HubSpot { "status": "error", "message": "This will be a human readable message with details about the error.", "errors": [ { "message": "This will be a message with additional details about the error", "in": "name" } ], "category": "VALIDATION_ERROR", "correlationId": "a43683b0-5717-4ceb-80b4-104d02915d8c" }

再試行

アプリまたは連携で、HubSpotが呼び出すエンドポイント（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時間になります。

参考になりましたか？
こちらのフォームではドキュメントに関するご意見をご提供ください。HubSpotがご提供しているヘルプはこちらでご確認ください。