エラー
Ikiform が返すすべてのエラーコードと、その HTTP ステータス、原因、対処。
フォームの送信と REST API は、同じエラーの形式を共有します。JSON のリクエストには対応する HTTP ステータスでこの形式が返り、ブラウザーからのフォーム送信には、同じメッセージとステータスでホストされたエラーページが表示されます。
エラーの形式
{
"ok": false,
"error": {
"code": "rate_limited",
"message": "Too many requests. Please slow down."
},
"request_id": "req_01k7v2c9t3e8m5q4x6z0a1b2c3"
}error.codeは安定しているので、分岐にはこれを使ってください。error.messageは人が読むための平易な英語で、変わることがあります。error.fieldsはバリデーションエラーのときに含まれ、フィールド ID をキーに、それぞれメッセージの一覧を持ちます。ボディ全体に関するエラーはキー_formを使います。error.challenge_urlはchallenge_requiredのときに含まれます。request_idは、すべてのレスポンスに付くX-Request-Idヘッダーと一致します。- レート制限のレスポンスには、秒数を示す
Retry-Afterが付きます。どちらのヘッダーもブラウザーのコードから読み取れます。
コード
| ステータス | コード | 発生する場所 |
|---|---|---|
| 400 | invalid_body | 送信 |
| 400 | invalid_request | API |
| 401 | unauthorized | API |
| 402 | plan_required | 送信 |
| 403 | forbidden | 両方 |
| 403 | origin_not_allowed | 送信 |
| 403 | form_paused | 送信 |
| 403 | captcha_failed | 送信 |
| 403 | challenge_required | 送信 |
| 404 | not_found | 両方 |
| 405 | method_not_allowed | API |
| 409 | idempotency_in_progress | 送信 |
| 413 | payload_too_large | 送信 |
| 415 | unsupported_media_type | 送信 |
| 415 | unsupported_charset | 送信 |
| 422 | validation_failed | 送信 |
| 422 | files_not_supported | 送信 |
| 422 | too_deep | 送信 |
| 422 | idempotency_mismatch | 送信 |
| 429 | rate_limited | 両方 |
| 429 | quota_exceeded | 送信 |
| 500 | server_error | 両方 |
400 invalid_body
| メッセージ | The request body could not be read. |
| 原因 | JSON や multipart の形式が不正、オブジェクトではなく JSON の配列や文字列を送った、または冪等キーが 255 文字を超えている。 |
| 対処 | JSON のオブジェクトを 1 つ送るか、ブラウザーや FormData にボディを組み立てさせてください。 |
400 invalid_request
| メッセージ | The request is invalid. |
| 原因 | limit、status、form_id、cursor のいずれかが無効です。メッセージにそのパラメーター名が入ります。 |
| 対処 | limit は 1〜100、status は received か spam、実在する frm_ の ID を使い、カーソルは返されたとおりに使ってください。 |
401 unauthorized
| メッセージ | A valid API key is required. |
| 原因 | Authorization ヘッダーがない、Bearer トークンではない、またはキーが存在しない、無効化された、期限切れ。 |
| 対処 | 有効なシークレットキーで Authorization: Bearer ik_sk_... を送ってください。 |
402 plan_required
| メッセージ | This form isn't accepting submissions right now. |
| 原因 | ワークスペースに有効なプランがありません。これはお支払いの仕組みが有効になって初めて起こりえます。 |
| 対処 | ダッシュボードの Settings でプランを選んでください。 |
403 forbidden
| メッセージ | You do not have access to this resource. |
| 原因 | API キーの形式が不正、別のワークスペースのもの、REST API で公開可能キーを使っている、または必要なスコープがない。 |
| 対処 | このワークスペースの、メッセージに示されたスコープを持つシークレットキーを使ってください。 |
403 origin_not_allowed
| メッセージ | This form does not accept submissions from this site. |
| 原因 | フォームの許可ドメイン外のサイトから送信され、フォームが不一致を拒否する設定になっている。または、キーに登録されていないドメインから公開可能キーが使われた。 |
| 対処 | サイトを Allowed domains（許可ドメイン）かキーのドメインに追加してください。サーバーからの送信には、シークレットキーを使ってください。 |
403 form_paused
| メッセージ | This form is not accepting submissions right now. |
| 原因 | ダッシュボードでフォームが一時停止されている。 |
| 対処 | フォームを再開してください。 |
403 captcha_failed
| メッセージ | The captcha check failed. Please try again. |
| 原因 | Turnstile のトークンがない、期限切れ、使用済み、または検証に失敗した。 |
| 対処 | 送信ごとに新しいトークンを取得してください。独自のキーを使う場合は、サイトキーがシークレットと対応しているか確認してください。 |
403 challenge_required
| メッセージ | Complete the human check, then send the form again. |
| 原因 | フォームが Ikiform の人間確認を使っていて、トークンのない JSON の送信が届いた。 |
| 対処 | SDK の challenge(formId) を呼び出してトークンを渡すか、error.challenge_url を使ってください。サーバーからの送信なら、代わりにシークレットキーを送れます。 |
404 not_found
| メッセージ | Not found. |
| 原因 | フォームが存在しない、削除または無効化された、または ID やルートが間違っている。/f/<formId> への GET でも返されます。 |
| 対処 | フォームの概要からエンドポイントをコピーし、タブで開くのではなく POST してください。 |
405 method_not_allowed
| メッセージ | This method is not allowed here. |
| 原因 | サーバー間専用の REST API に対する、ブラウザーのプリフライト。 |
| 対処 | /api/v1 はバックエンドから呼び出してください。 |
409 idempotency_in_progress
| メッセージ | A request with this idempotency key is still being processed. |
| 原因 | この冪等キーのリクエストがまだ処理中です。 |
| 対処 | 少し待ってから同じキーでリトライしてください。最初の応答が返ります。 |
413 payload_too_large
| メッセージ | The submission is too large. |
| 原因 | ボディ、フィールド名、値、フィールドの数のいずれかが上限を超えている。どれかはメッセージに示されます。 |
| 対処 | 制限を参照してください。長いテキストは複数のフィールドに分けるか、ファイルは別の場所に保存してリンクを送ってください。 |
415 unsupported_media_type
| メッセージ | Send the form as urlencoded, multipart or JSON. |
| 原因 | Content-Type が urlencoded、multipart、JSON のいずれでもない、または指定されていない。 |
| 対処 | JSON を送るときは Content-Type: application/json を設定してください。 |
415 unsupported_charset
| メッセージ | Only UTF-8 is supported. |
| 原因 | ボディが UTF-8 ではない、または別の文字コードを宣言している。 |
| 対処 | UTF-8 でエンコードしてください。古い HTML フォームには accept-charset="utf-8" を追加してください。 |
422 validation_failed
| メッセージ | Some fields are invalid. |
| 原因 | フィールドがバリデーションに失敗した。error.fields はフィールド ID をメッセージに対応づけます。 |
| 対処 | メッセージをフィールドの横に表示してください。フィールドを参照してください。 |
422 files_not_supported
| メッセージ | File uploads are not supported yet. |
| 原因 | 送信にファイルが含まれている。ファイルのアップロードはまだ実装されていません。 |
| 対処 | ファイルの入力欄を削除するか、ファイルは別の場所にアップロードしてリンクを送信してください。 |
422 too_deep
| メッセージ | The JSON body is nested too deeply. |
| 原因 | JSON のボディが、トップレベルのオブジェクトを含めて 3 階層を超えてネストしている。 |
| 対処 | { "address_city": "London" } のように、データを平らにしてください。 |
422 idempotency_mismatch
| メッセージ | This idempotency key was already used with a different payload. |
| 原因 | この冪等キーは、直近 24 時間以内にこのフォームで、異なるフィールドとともにすでに使われている。 |
| 対処 | 新しいデータには新しいキーを使ってください。同じキーは完全に同じリトライにだけ使ってください。 |
429 rate_limited
| メッセージ | Too many requests. Please slow down. |
| 原因 | レート制限を超えた。Retry-After に待つべき秒数が示されます。 |
| 対処 | 待ってからリトライしてください。本物の訪問者が制限に達する場合は、フォームのレート制限を変更してください。 |
429 quota_exceeded
| メッセージ | This form isn't accepting submissions right now. |
| 原因 | ワークスペースが今月、月間の送信数の上限の 2 倍を受信した。 |
| 対処 | アップグレードするか、翌月まで待ってください。月間の使用量を参照してください。 |
500 server_error
| メッセージ | Something went wrong on our side. |
| 原因 | Ikiform 側で問題が発生した。 |
| 対処 | バックオフと冪等キーを使ってリトライしてください。問題が続く場合は、request_id を伝えてください。 |
エラーにならないもの
- スパムにも、本物の送信と同じ
201またはリダイレクトが返ります。ダッシュボードのスパムフィルターの下で確認してください。 - 許可されていない
_redirectは無視され、ブラウザーはホストされたサンクスページに移動します。 - 有効なメールアドレス 1 つではない
_replytoは無視されます。
リトライ
429はRetry-Afterの後に、500、409、ネットワークエラーはバックオフを付けてリトライしてください。冪等キーを送れば、リトライで重複が作られることはありません。- その他の
4xxエラーは、そのままリトライしないでください。先にリクエストを直してください。