Skip to content
RocketLead Developers

Troubleshooting

Form doesn’t render

Section titled “Form doesn’t render”
  • Open the browser console and check that widget.js loads — no 404 on https://cdn.rocketlead.io/static/forms/widget.js.
  • Confirm the form is published. Drafts return 404 from /availability and the widget gives up silently.
  • Verify the data-form-id matches the form ID in the editor. Copy-paste from the Embed code dialog rather than retyping.
  • For SPAs, check that you’re using window.rocketlead.forms.create() — the auto-mount only fires once per page load.

Form is unstyled

Section titled “Form is unstyled”

widget.css failed to load. Without the stylesheet you’ll see raw HTML controls. Check the <link rel="stylesheet"> URL and CORS / CDN connectivity.

Form is too wide

Section titled “Form is too wide”

The widget fills its container. Constrain it with a wrapper:

<div style="max-width: 600px; margin: 0 auto;">
    <div data-rocketlead-form data-form-id="abc-123-def"></div>
</div>

403 on submission

Section titled “403 on submission”

Two common causes:

  1. The page’s Origin isn’t in the form’s Erlaubte Domains list (see Allowed Domains).
  2. Captcha verification failed — the token is missing, expired, or the user didn’t solve the challenge.

Check the response body for the specific error message. If you’re getting 403 Origin not allowed from a backend service that shouldn’t have an Origin header at all, a proxy is likely forwarding it — check your CDN/proxy config.

429 errors

Section titled “429 errors”

The public API is rate-limited per formId + IP:

  • /availability, /slots, /appointment-types — 30/min.
  • /submit — 5/min.
  • /telemetry — 120/min.

Aggressive testing or burst submissions trigger 429. See Public API → Rate limits.

SPA: form is empty after route change

Section titled “SPA: form is empty after route change”

You’re using the Quick Start (<script async> + [data-rocketlead-form]) inside a client-routed app. The widget only scans on DOMContentLoaded — re-mounted containers stay empty.

Switch to create() and wire unmount() into your component cleanup.

SPA: form mounts twice

Section titled “SPA: form mounts twice”

You called create() twice without unmounting the first instance. create() is idempotent on the same target — it unmounts the previous instance automatically — so this is usually fine. If you’re seeing duplicated DOM, check that:

  • Your cleanup hook actually runs (React StrictMode runs effects twice in dev — unmount() should handle that).
  • You’re not re-rendering and re-creating the target ref unnecessarily.

Booking slot says “no longer available” right after picking it

Section titled “Booking slot says “no longer available” right after picking it”

Race between the availability fetch and the submit. The slot was free when displayed, then someone else booked it before you submitted. The widget surfaces this as a 400 error with the message The selected time slot is no longer available. Refetch availability and let the user pick another slot.

See Field Types → booking-calendar for the double-check that produces this error.

Phone number gets reformatted on submit

Section titled “Phone number gets reformatted on submit”

That’s intentional — tel fields are normalized to E.164 server-side. The persisted value (and webhook payload) carry the E.164 string, not what the user typed. See Field Types → tel.

Webhook never arrives

Section titled “Webhook never arrives”
  • Confirm the form’s webhook URL is https:// — http:// is rejected at delivery time.
  • Check your receiver returns a 2xx response within 10 seconds. Anything else triggers a retry; after 5 attempts the delivery is failed.
  • Check the form’s Deliveries view in the admin console — the captured response body (truncated to 4096 chars) often pinpoints the issue.
Section titled “Related”