トラブルシューティング

開発者向けAPIを使用する際の問題について診断し、解決策を提供するドキュメントです。

Table of contents

  1. REST API
    1. クエリパラメータが正しく認識されません。または、フォーマット不正のため400 Bad Requestが返ってきます。
    2. クエリパラメータに配列を指定しても、正しく認識されません。または、「”invalid_parameter”: “Invalid request: value at root is not an array” 」というエラーになる
    3. 「expected XXX, but received YYY」というエラーになります。
    4. 「invalid_parameter: フィールドコードが不正です」というエラーになります。
      1. フィールドコードの指定に誤りがある
      2. ワークフローの「承認者による上書き」の設定に従っていない
    5. 「endpoint_not_found」というエラーになります。
  2. Webhook API
    1. X-Kickflow-Signatureと受信したペイロードとシークレットからHMAC-SHA256を計算した値が一致しません。

REST API

クエリパラメータが正しく認識されません。または、フォーマット不正のため400 Bad Requestが返ってきます。

よくある原因として、クエリパラメータがURLエンコードされていないことが挙げられます。 リクエストに使用するツールやサービスによっては、クエリパラメータを自動的にURLエンコードしてくれない場合があります。 その場合、クエリパラメータに含まれる特殊文字（例: @, + など）を手動でURLエンコードする必要があります。

例えば、メールアドレスからユーザーを取得するAPIの場合、クエリパラメータにはURLエンコードされたメールアドレスを指定する必要があります。

// NG: URLエンコードされていないメールアドレスを指定
GET /v1/users/lookupByEmail?email=foo@example.com

// OK: URLエンコードされたメールアドレスを指定
GET /v1/users/lookupByEmail?email=foo%40example.com

別の例として、チケット検索APIで日時による絞り込みを行う場合、クエリパラメータにはURLエンコードされたISO8601形式の日時を指定する必要があります。

// NG: URLエンコードされていないISO8601形式の日時を指定
GET /v1/tickets?createdAtStart=2023-10-01T00:00:00+09:00

// OK: URLエンコードされたISO8601形式の日時を指定
GET /v1/tickets?createdAtStart=2023-10-01T00%3A00%3A00%2B09%3A00

クエリパラメータに配列を指定しても、正しく認識されません。または、「”invalid_parameter”: “Invalid request: value at root is not an array” 」というエラーになる

クエリパラメータに配列を指定する方法が間違っています。正しい形式で指定しているかご確認ください。

// OK
/v1/tickets?status[]=in_progress&status[]=completed

// NG: カンマ区切りの文字列
/v1/tickets?status=in_progress,completed

// NG: []を使用しない
/v1/tickets?status=in_progress&status=completed

「expected XXX, but received YYY」というエラーになります。

エンドポイントのパラメーターが要求する型に対して、実際にリクエストをしたデータの型に誤りがあります。
XXXにはエンドポイントが要求する型、YYYにはリクエストされた型が表示されるので、要求されているXXXの型でリクエストをするように処理の見直しをしてください。

例えば、idsという「UUID文字列の配列」を要求するパラメーターに対して、UUID文字列を指定した場合は「... expected array, but received String: ...」のようなエラーメッセージが返されます。

idsへの正しい指定（UUID文字列の配列） idsへの誤った指定（UUID文字列）
[“12345678-1234-5678-1234-123456789012”] “12345678-1234-5678-1234-123456789012”

「invalid_parameter: フィールドコードが不正です」というエラーになります。

REST APIからチケットを更新する際に発生する「フィールドコードが不正です」というエラーは、次にあるようないくつかのケースで発生します。

フィールドコードの指定に誤りがある

入力ミスなどにより、存在しないフィールドコードがAPIリクエストで指定されていることが考えられます。 ワークフローの各セクションのフォームに、指定したフィールドコードに該当するフィールドが存在するかご確認ください。

ワークフローの「承認者による上書き」の設定に従っていない

ワークフローの「承認者による上書き」の設定に応じて、チケットを更新するリクエストボディに含めているフィールドに過不足がないかご確認ください。

  • 「承認者による上書き」の設定が「承認者用フィールドのみ上書き可能（デフォルト）」の場合
    • REST APIのリクエストボディには、各フィールドの「入力可能なユーザー」の設定で「承認者が入力可能」にチェックが付いているフィールドのみを含めるようにしてください。
    • 「申請者が入力可能」と「承認者が入力可能」の両方にチェックが付いている場合も同様です。
  • 「承認者による上書き」の設定が「すべてのフィールドを上書き可能」の場合
    • REST APIのリクエストボディには、すべてのフィールドを含めるようにしてください。

「endpoint_not_found」というエラーになります。

REST APIのリクエストエンドポイントのURLの指定が正しいかご確認ください。

指定が正しいのにも関わらずendpoint_not_foundのエラーとなる場合は、REST APIにリクエストする際のHTTPメソッドが誤っていることが考えられます。 APIの仕様をご確認のうえ、正しいHTTPメソッドでリクエストがされているかご確認ください。

curlコマンドで検証する場合は、HTTPメソッドを--requestオプションで明示的に指定してください。指定しない場合は、GETメソッドによるリクエストとなります。

例）現在のユーザーを取得する

curl --location https://api.kickflow.com/v1/user \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer xxxx' \
  --request GET

Webhook API

X-Kickflow-Signatureと受信したペイロードとシークレットからHMAC-SHA256を計算した値が一致しません。

Webhook APIで送信されるペイロードのJSON文字列に含まれる &, <, > の文字はそれぞれ以下のコードにエスケープされ、X-Kickflow-Signatureを算出する際は、エスケープされた状態の文字列でHMAC-SHA256を計算します。

  • &: \u0026
  • <: \u003c
  • >: \u003e

WebhookのペイロードとシークレットからHMAC-SHA256を計算する際に、上記の文字列をアンエスケープして計算するとX-Kickflow-Signatureと一致しなくなります。 必ず受信したペイロードをそのまま使用して計算した値とX-Kickflow-Signatureを比較してください。

Copyright © 2025 kickflow, Inc.