Error

Setiap kode error yang dikembalikan Ikiform, beserta status HTTP, penyebab, dan solusinya.

Kiriman formulir dan REST API memakai satu envelope error yang sama. Request JSON mendapatkannya dengan status HTTP yang sesuai; kiriman formulir dari browser mendapat halaman error hosted dengan pesan dan status yang sama.

Envelope error

Error

{
  "ok": false,
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Please slow down."
  },
  "request_id": "req_01k7v2c9t3e8m5q4x6z0a1b2c3"
}

error.code stabil; jadikan acuan percabangan. error.message berupa bahasa Inggris biasa untuk manusia dan bisa berubah.
error.fields ada pada error validasi, diberi key berdasarkan ID field, masing-masing dengan daftar pesan. Error tentang seluruh body memakai key _form.
error.challenge_url ada pada challenge_required.
request_id sama dengan header X-Request-Id yang dibawa setiap respons.
Respons yang terkena rate limit membawa Retry-After dalam detik. Kedua header bisa dibaca dari kode browser.

Kode

Status	Kode	Tempat
400	`invalid_body`	Kirim
400	`invalid_request`	API
401	`unauthorized`	API
402	`plan_required`	Kirim
403	`forbidden`	Keduanya
403	`origin_not_allowed`	Kirim
403	`form_paused`	Kirim
403	`captcha_failed`	Kirim
403	`challenge_required`	Kirim
404	`not_found`	Keduanya
405	`method_not_allowed`	API
409	`idempotency_in_progress`	Kirim
413	`payload_too_large`	Kirim
415	`unsupported_media_type`	Kirim
415	`unsupported_charset`	Kirim
422	`validation_failed`	Kirim
422	`files_not_supported`	Kirim
422	`too_deep`	Kirim
422	`idempotency_mismatch`	Kirim
429	`rate_limited`	Keduanya
429	`quota_exceeded`	Kirim
500	`server_error`	Keduanya

400 invalid_body

Pesan	`The request body could not be read.`
Penyebab	JSON atau multipart yang rusak, array atau string JSON alih-alih objek, atau idempotency key lebih dari 255 karakter.
Solusi	Kirim satu objek JSON, atau biarkan browser atau `FormData` yang menyusun body.

400 invalid_request

Pesan	`The request is invalid.`
Penyebab	`limit`, `status`, `form_id`, atau `cursor` tidak valid. Pesannya menyebut parameternya.
Solusi	Gunakan `limit` 1 sampai 100, `status` `received` atau `spam`, ID `frm_` yang nyata, dan cursor persis seperti yang dikembalikan.

401 unauthorized

Pesan	`A valid API key is required.`
Penyebab	Tidak ada header `Authorization`, bukan Bearer token, atau key yang tidak dikenal, dicabut, atau kedaluwarsa.
Solusi	Kirim `Authorization: Bearer ik_sk_...` dengan secret key yang aktif.

402 plan_required

Pesan	`This form isn't accepting submissions right now.`
Penyebab	Workspace tidak punya paket aktif. Ini hanya bisa terjadi setelah penagihan diaktifkan.
Solusi	Pilih paket di dashboard pada Settings.

403 forbidden

Pesan	`You do not have access to this resource.`
Penyebab	Kunci API salah format, milik workspace lain, berupa publishable key di REST API, atau tidak punya scope yang dibutuhkan.
Solusi	Gunakan secret key dari workspace ini dengan scope yang disebut di pesan.

403 origin_not_allowed

Pesan	`This form does not accept submissions from this site.`
Penyebab	Kiriman berasal dari situs di luar domain yang diizinkan formulir dan formulir menolak ketidakcocokan, atau publishable key dipakai dari domain yang tidak tercantum di key.
Solusi	Tambahkan situs ke Allowed domains atau ke domain key. Untuk kiriman dari server, gunakan secret key.

403 form_paused

Pesan	`This form is not accepting submissions right now.`
Penyebab	Formulir dijeda di dashboard.
Solusi	Lanjutkan formulir.

403 captcha_failed

Pesan	`The captcha check failed. Please try again.`
Penyebab	Token Turnstile tidak ada, kedaluwarsa, sudah dipakai, atau gagal diverifikasi.
Solusi	Ambil token baru untuk setiap kiriman. Dengan key Anda sendiri, pastikan site key cocok dengan secret-nya.

403 challenge_required

Pesan	`Complete the human check, then send the form again.`
Penyebab	Formulir memakai pemeriksaan manusia Ikiform dan kiriman JSON tiba tanpa token.
Solusi	Panggil `challenge(formId)` dari SDK dan berikan tokennya, atau gunakan `error.challenge_url`. Kiriman dari server bisa mengirim secret key sebagai gantinya.

404 not_found

Pesan	`Not found.`
Penyebab	Formulir tidak ada, sudah dihapus atau dinonaktifkan, atau ID atau route-nya salah. Juga dikembalikan untuk `GET` ke `/f/<formId>`.
Solusi	Salin endpoint dari ringkasan formulir, dan kirim POST alih-alih membukanya di tab.

405 method_not_allowed

Pesan	`This method is not allowed here.`
Penyebab	Preflight browser pada REST API, yang hanya untuk server ke server.
Solusi	Panggil `/api/v1` dari backend Anda.

409 idempotency_in_progress

Pesan	`A request with this idempotency key is still being processed.`
Penyebab	Request dengan idempotency key ini masih diproses.
Solusi	Tunggu sebentar dan coba ulang dengan key yang sama; Anda akan mendapat respons pertama.

413 payload_too_large

Pesan	`The submission is too large.`
Penyebab	Body, nama field, nilai, atau jumlah field melewati batasnya. Pesannya menyebut yang mana.
Solusi	Lihat Batas. Pecah teks panjang ke beberapa field atau simpan file di tempat lain dan kirim tautannya.

415 unsupported_media_type

Pesan	`Send the form as urlencoded, multipart or JSON.`
Penyebab	`Content-Type` bukan urlencoded, multipart, atau JSON, atau tidak ada.
Solusi	Atur `Content-Type: application/json` saat mengirim JSON.

415 unsupported_charset

Pesan	`Only UTF-8 is supported.`
Penyebab	Body bukan UTF-8, atau mendeklarasikan charset lain.
Solusi	Encode sebagai UTF-8. Tambahkan `accept-charset="utf-8"` ke formulir HTML lama.

422 validation_failed

Pesan	`Some fields are invalid.`
Penyebab	Field gagal validasi. `error.fields` memetakan ID field ke pesan.
Solusi	Tampilkan pesan di samping field. Lihat Field.

422 files_not_supported

Pesan	`File uploads are not supported yet.`
Penyebab	Kiriman berisi file. Unggah file belum tersedia.
Solusi	Hapus input file, atau unggah file di tempat lain dan kirim tautannya.

422 too_deep

Pesan	`The JSON body is nested too deeply.`
Penyebab	Body JSON bertingkat lebih dari 3 level, termasuk objek teratas.
Solusi	Ratakan datanya, misalnya `{ "address_city": "London" }`.

422 idempotency_mismatch

Pesan	`This idempotency key was already used with a different payload.`
Penyebab	Idempotency key ini sudah dipakai untuk formulir ini dalam 24 jam terakhir dengan field yang berbeda.
Solusi	Gunakan key baru untuk data baru. Pakai key yang sama hanya untuk percobaan ulang yang persis sama.

429 rate_limited

Pesan	`Too many requests. Please slow down.`
Penyebab	Melewati rate limit. `Retry-After` menyebut berapa detik harus menunggu.
Solusi	Tunggu dan coba ulang. Jika pengunjung sungguhan mengalaminya, ubah rate limit formulir.

429 quota_exceeded

Pesan	`This form isn't accepting submissions right now.`
Penyebab	Workspace menerima 2 kali batas kiriman bulanannya bulan ini.
Solusi	Upgrade, atau tunggu bulan berikutnya. Lihat Pemakaian bulanan.

500 server_error

Pesan	`Something went wrong on our side.`
Penyebab	Ada yang gagal di pihak Ikiform.
Solusi	Coba ulang dengan backoff dan idempotency key. Jika terus terjadi, sertakan `request_id`.

Bukan error

Spam mendapat 201 atau redirect yang sama seperti kiriman asli. Cari di filter spam di dashboard.
_redirect yang tidak diizinkan akan diabaikan, dan browser mendarat di halaman terima kasih hosted.
_replyto yang bukan satu alamat email valid akan diabaikan.

Mencoba ulang

Coba ulang 429 setelah Retry-After, dan 500, 409, atau error jaringan dengan backoff. Kirim idempotency key agar percobaan ulang tidak pernah membuat duplikat.
Jangan coba ulang error 4xx lain tanpa perubahan. Perbaiki request-nya terlebih dahulu.