トラブルシューティング

CORS エラー、オリジンの不一致、challenge_required、429、不明なフィールド、使用量の上限エラーの対処法。

まずはレスポンスを確認しましょう。Ikiform からの応答にはすべて X-Request-Id ヘッダーが付き、エラーの場合は安定した error.code もあります。この curl は、サイトが送るのと同じオリジンから両方を表示します:

ターミナル

curl -i https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Origin: https://example.com" \
  -d '{"email":"ada@example.com"}'

Ikiform 自体から 5xx エラーやタイムアウトが返っていますか？まず status.ikiform.com で現在の障害を確認してください。

ブラウザーで CORS によりリクエストがブロックされたと表示される

送信エンドポイントはすべてのオリジンを許可しているので、本当に CORS で失敗している場合、たいていはリクエストが Ikiform に届いていないか、間違った URL に送られています。

URL が https://ikiform.com/f/<formId> で、frm_xxxxxxxxxxxxxxxx のような完全な frm_ の ID を含み、後ろに余分なパスがないか確認してください。
ブラウザーから /api/v1 を呼び出している。REST API は設計上ブラウザーを拒否します。サーバーから呼び出してください。
広告ブロッカー、プライバシー保護の拡張機能、企業のプロキシがリクエストをブロックした。拡張機能のないプライベートウィンドウで試してください。
サイト自身の Content-Security-Policy がブロックしている。connect-src に https://ikiform.com を追加し、プレーンな HTML の送信なら form-action にも追加してください。

プリフライトを直接確認します。オリジンをそのまま返して 204 で応答するはずです:

ターミナル

curl -i -X OPTIONS https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx \
  -H "Origin: https://example.com" \
  -H "Access-Control-Request-Method: POST" \
  -H "Access-Control-Request-Headers: content-type"

送信データが origin_mismatch でスパムに入る

フォームに許可ドメインがあり、それ以外の場所から送信されています。ダッシュボードのスパムの理由に origin_mismatch が表示されます。

www、ステージング、プレビューのドメインも含め、フォームを配信するすべてのドメインを追加してください。登録したドメインのサブドメインは自動的に一致します。
ローカルで開発する間は localhost を追加してください。
自分のサーバーからの送信には Origin がありません。チェックをスキップするシークレットキーを送ってください。
Mark as spam ではなく Reject を選んでいる場合、同じ送信には 403 origin_not_allowed が返ります。

403 challenge_required

フォームのスパムチェックが Ikiform に設定されていて、送信に Turnstile のトークンがありませんでした。

ブラウザーのコード: 送信の直前に毎回 SDK の challenge(formId) を呼び出し、トークンを turnstileToken として submit に渡してください。
サーバーのコード: シークレットキーで Authorization: Bearer ik_sk_... を送ってください。シークレットキーはチェックをスキップします。
プレーンな HTML の送信でこのコードが返ることはなく、代わりに確認ページが表示されます。フォームの送信でこれが返る場合は、何かが Accept: application/json を送っています。
curl でテストしていますか？テスト用のフォームではチェックをオフにするか、シークレットキーを使ってください。

403 captcha_failed は、トークンは送られたものの検証に失敗したという意味です。トークンは 1 回限りで 300 秒で期限切れになるので、試行ごとに新しいものを取得してください。

429 rate_limited

Retry-After を読み取り、その秒数だけ待ってください。
手動でテストしていますか？標準のプリセットは、1 つの IP から 1 分に 5 件、10 秒に 3 件までです。テスト用のフォームは緩めに切り替えてください。
すべての訪問者の送信をサーバーから送っていますか？すべての送信がサーバーの IP を共有します。ブラウザーから送信するか、緩めかカスタムを選んでください。
オフィスやイベントのネットワークにいる多くの人も、1 つの IP を共有します。緩めなら 1 分に 20 件まで送れます。

Unknown field を含む 422

フォームにフィールドが定義されていて、定義にない名前が送信されました。error.fields にその名前が示されます。例: { "website": ["Unknown field \"website\""] }。

フィールドを定義に追加するか、入力欄を削除してください。
自分用のマーカーなら、入力欄の名前を _ で始めてください。予約済みの名前はバリデーションされずに除外されます。
ハニーポットの名前が、フォームの Honeypot field（ハニーポットフィールド）の設定と一致しているか確認してください。
フィールド ID は小文字の snake_case です。マークアップの firstName は、定義の first_name とは別物です。

429 quota_exceeded

ワークスペースが今月、月間の上限の 2 倍を受信したため、翌月になるかワークスペースがアップグレードするまで送信を受け付けません。月間の使用量を参照してください。

送信データが表示されない

スパムフィルターの下を確認してください。スパムにも通常の成功の応答が返るので、訪問者には区別がつきません。
フォームが一時停止されていないか、action の ID がダッシュボードと一致しているか確認してください。
ブラウザーからの送信で Ikiform のエラーページが表示された場合は、拒否されています。ページに理由が表示されます。

Webhook が失敗する

no_matching_signature: JSON を解析する前の生のボディで検証し、正しい whsec_ のシークレットをコピーしたか確認してください。配信を検証ツールに貼り付けて確認できます。
timestamp_too_old: サーバーの時計がずれているか、古い配信をリプレイしています。
タイムアウト: 15 秒以内に応答し、時間のかかる処理はその後に行ってください。
リダイレクトには従いません。フレームワークが求める末尾のスラッシュも含め、最終的な URL を使ってください。
5 日間の失敗または 410 でエンドポイントが無効化されました。問題を直してから、エンドポイントのページで再びオンにしてください。