Troubleshooting

“CSRF violation: Invalid Origin” / a 403 with no submission stored

Your form has allowed_origins configured, and the request came from somewhere not on that list.

403

{ "error": "Origin not permitted to submit to this form." }

Check the form’s Allowed Origins setting — leave it empty to accept submissions from any origin (the default) while you’re testing across environments.

My submission landed in Suspicious instead of Valid

The success response looks completely normal — the tell is in the dashboard, not the API response:

201 — still a success response

{ "success": true, "submission_id": "sub_pub_1a2b3c", "submission_number": 43 }

Almost always one of:

CAPTCHA is configured but no token was sent — either you’re on the No-JS path (which can’t run CAPTCHA at all), or the widget failed to load client-side (ad blocker, CSP, a slow/blocked script).
Elevated recent submission volume from the same identity in a short window (rate-limit and repeated-failure signals).

Check the Activity tab for the exact signals that fired on that specific submission.

My submission was blocked entirely (never stored)

403

{ "error": "This submission was flagged as spam. If you believe this is a mistake, please reload the form and try again." }

Only two things block outright: a filled honeypot field, or a CAPTCHA token that was actually verified as invalid (not just missing — missing alone never blocks by itself). If you’re testing with a script or a tool that auto-fills every input on a page, it likely filled the honeypot field too — real forms hide it with CSS, but a naive “fill every input” script doesn’t respect that.

”Idempotency-Key was already used with a different payload”

409

{ "error": "Idempotency-Key was already used with a different payload.", "code": "IDEMPOTENCY_KEY_REUSED" }

You reused an Idempotency-Key header value across two submissions with different data:

const form = client.form('YOUR_PUBLIC_ID');

// Wrong — same key, different data on each call
await form.submit({ email: 'a@example.com' }, { idempotencyKey: 'fixed-key' });
await form.submit({ email: 'b@example.com' }, { idempotencyKey: 'fixed-key' }); // 409

// Right — a fresh key per logical attempt
import { randomUUID } from 'crypto';
await form.submit({ email: 'a@example.com' }, { idempotencyKey: randomUUID() });
await form.submit({ email: 'b@example.com' }, { idempotencyKey: randomUUID() }); // fine

Reuse a key only when retrying the exact same attempt (e.g. after a network timeout) — the SDK does this automatically if you don’t pass one yourself.

My No-JS form doesn’t show any error message

Expected — there’s no client-side error UI on that path by design (no JS to render one). On failure, Raykoi redirects to your redirect field’s URL (or the page’s own Referer) with ?raykoi_error=... appended:

https://yoursite.com/thanks?raykoi_error=Enter+a+valid+email+address

Read that query param to display the message yourself:

const params = new URLSearchParams(window.location.search);
const error = params.get('raykoi_error');
if (error) {
  document.getElementById('error-banner').textContent = error;
}

See No JavaScript.

File upload fields don’t work on my No-JS form

Expected — not currently supported. The upload flow is inherently a multi-step, JavaScript-orchestrated exchange (fetch a signed URL, then PUT to it) that a plain <form> POST can’t perform. See File Uploads.

I’m being rate limited and don’t think I should be

429

{ "error": "Too many submissions. Please wait a moment before trying again." }

Check which endpoint — limits are per-endpoint, not global:

Endpoint	Limit
Submit	20 / minute
Schema fetch	60 / minute
Validate	30 / minute

Full table in API Overview. If you’re validating on every keystroke client-side, batch or debounce those calls:

const form = client.form('YOUR_PUBLIC_ID');

// Instead of validating on every keystroke...
input.addEventListener('input', () => form.validate(data)); // too many calls

// ...validate on blur, or debounce
input.addEventListener('blur', () => form.validate(data));

My webhook stopped firing

Check the form’s Webhooks settings — a webhook that fails repeatedly is automatically disabled and the workspace owner is emailed, rather than retried forever against a permanently broken endpoint. Re-enable it once you’ve fixed the receiving end. See Webhooks.

My webhook signature verification always fails

The most common cause: you’re computing the HMAC over a re-parsed/re-serialized body instead of the exact raw bytes received. JSON re-serialization can reorder keys or change whitespace, producing a different signature than what Raykoi actually signed.

// Wrong — re-serializing loses byte-for-byte fidelity
app.post('/webhook', express.json(), (req, res) => {
  const body = JSON.stringify(req.body); // NOT the original bytes
  verifyWebhook(secret, timestamp, body, signature); // will fail
});

// Right — verify against the raw body
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const body = req.body.toString('utf8'); // exact bytes Raykoi sent
  verifyWebhook(secret, timestamp, body, signature); // correct
});

See Webhooks for the full verification snippet.

​“CSRF violation: Invalid Origin” / a 403 with no submission stored

​My submission landed in Suspicious instead of Valid

​My submission was blocked entirely (never stored)

​”Idempotency-Key was already used with a different payload”

​My No-JS form doesn’t show any error message

​File upload fields don’t work on my No-JS form

​I’m being rate limited and don’t think I should be

​My webhook stopped firing

​My webhook signature verification always fails