Form Filling SDK Error Handling

Fix common Form filling SDK issues with template IDs, auth, layout, and error codes

When you call client.start() or render FormFilling, the SDK loads the Form filling interface inside an iframe in your app. If an error occurs while loading or during the session, the SDK returns a SukiFormFillingError.

start() does not throw errors directly. Instead, handle errors using the onError callback, the form-filling:error event, or, in React, the error value returned by useFormFilling().

Some problems do not emit an error code at all. The container may look empty if it has no height, if CSP blocks the iframe, or if partner credentials are invalid. For those cases, see Blank UI with no error code below.

After most errors, the SDK removes the iframe and the clinician may need to open Form filling UI again.

Choose the right error event

Where you listen	When to use it
onError on FormFillingClient	JavaScript or React; one handler when you create the client
form-filling:error on the client	JavaScript when you prefer client.on() for logging or analytics
error from useFormFilling()	React; show a banner anywhere inside FormFillingProvider

Each error reaches onError and form-filling:error listeners. Pick one pattern unless you need both.

Refer to the Error handling example for React and JavaScript code.

Form filling SDK error codes

Code	Reason	When it happens	What to do
SUKI_FF_001	empty-template-ids	No forms after resolve (neither usable forms nor form_template_ids)	Pass at least one static or dynamic entry in forms
SUKI_FF_001	unsupported-template-ids	All static IDs unknown to the catalogue and no valid dynamic entries remain	Confirm enabled template_id values with Suki support, or add a valid schema entry
SUKI_FF_001	invalid-form-entry	XOR violated (both / neither / static+schema), or non-JSON-serializable React props	Fix each entry to use exactly one of form_template_id or schema
SUKI_FF_001	duplicate-form-id	Duplicate form_template_id among static entries, or duplicate forms[].id among dynamic entries	Make static IDs unique among themselves and dynamic id values unique among themselves
SUKI_FF_002	handshake-timeout	The iframe did not complete ready -> init-ack within 10 seconds	Check network, HTTPS, and CSP frame-src
SUKI_FF_003	fetch-templates-failed	GET /api/v1/info/suki-medical-form-templates failed during validation	Retry; confirm auth and staging vs production
SUKI_FF_004	iframe-runtime	A runtime error in the Form filling interface (includes server schema validation failures after start)	Show retry; check microphone permission, network, and schema field rules

JavaScript

import { SukiFormFillingError } from "@suki-sdk/form-filling";

client.on("form-filling:error", (err) => {
  if (err instanceof SukiFormFillingError) {
    console.error(err.code, err.reason, err.message);
  }
});

SUKI_FF_004 messages

When the SDK returns SUKI_FF_004, the reason is always iframe-runtime. The message field provides more detail about what failed and may contain one of the following values:

• Failed to start form filling session..
• Failed to submit form filling session..
• Form generation failed..

Use code and reason to identify the error in your application. Use message only to display information to users or to include in logs.

Troubleshooting Form filling issues

If Form filling does not load or is not working as expected, check these common issues in order:

1. Verify that the container has a height. See Blank UI below.
2. Verify that your forms (or form_template_ids when forms is omitted) resolve to at least one valid entry. See Template and form issues below.
3. Verify that partnerId and partnerToken are configured correctly through SukiAuthManager.
4. Verify that your Content Security Policy (CSP) allows the SDK iframe and that your app is running over HTTPS so microphone access is available.

Blank UI with no error code

If the Form filling interface does not appear and onError is never called, the iframe most likely did not become visible. This is usually caused by a layout or container sizing issue rather than a problem with the Form filling session itself.

Checking container height

The SDK appends a full-size iframe to your container. If the container has zero height, the iframe loads but you see a blank area.

In JavaScript, set height on the element you pass as rootElement:

HTML

<div id="suki-form-container" style="width: 100%; height: 600px;"></div>

In React, style the wrapper FormFilling renders:

CSS

.suki-form-filling {
  width: 100%;
  height: 600px;
}

Refer to Configuration for container sizing.

Checking CSP

Form filling runs in an iframe from Suki’s SDK host. If your app’s Content-Security-Policy header blocks that origin in frame-src, the iframe cannot load. You may see a blank container or SUKI_FF_002 (handshake-timeout).

Environment	Add to frame-src
Production	https://sdk.suki.ai
Staging	https://sdk.suki-stage.com

Checking partner credentials

Form filling does not open until SukiAuthManager sign-in succeeds with a valid partnerId and partnerToken. If credentials are wrong or expired, the Form filling interface may never appear and you may not receive an SDK error code.

Refer to Authentication and Partner onboarding to get your credentials.

Checking HTTPS and microphone

Run Form filling on HTTPS. The browser requires a secure context for microphone access.

Template and form issues

Before the iframe opens, FormFillingClient.start() resolves forms (or form_template_ids when forms is omitted) and validates static IDs against Suki’s medical form template catalogue.

• Prefer forms. When forms is provided, form_template_ids is ignored.
• Template IDs are different for staging and production environments.
• Unsupported static IDs are dropped before the UI opens. Valid dynamic schema entries stay in the session.
• If no forms remain after validation, the SDK emits SUKI_FF_001 (empty-template-ids or unsupported-template-ids) and does not open the UI.
• Invalid XOR entries or duplicate IDs fail before the network with invalid-form-entry or duplicate-form-id.

Symptom	Likely cause
Immediate SUKI_FF_001 (empty-template-ids)	No forms after resolve
Immediate SUKI_FF_001 (unsupported-template-ids)	No static IDs matched and no valid dynamic entries remain
Immediate SUKI_FF_001 (invalid-form-entry)	Both / neither of form_template_id and schema, or non-serializable React props
Immediate SUKI_FF_001 (duplicate-form-id)	Duplicate static form_template_id or duplicate dynamic id
Fewer forms than you passed	Some static IDs were invalid and were dropped
SUKI_FF_003	Template list could not be loaded during validation
SUKI_FF_004 after start	Server rejected a schema field rule

Contact Suki’s Support team to confirm staging and production template_id values. Refer to Form filling templates for supported assessment types and Dynamic Form filling for partner schemas.

Handling normal session outcomes

Some session outcomes are normal and do not emit SukiFormFillingError: In these cases, the SDK does not return an error code. To deal with these scenarios, check the structured_data.non_generated_values field in the FormFillingResult object returned by the onSubmit callback.

Situation	What happens
Some forms produce output, others do not	Check structured_data.non_generated_values in FormFillingResult on onSubmit
Processing takes longer than 60 seconds (online)	Form filling interface enters a timeout phase. If the clinician leaves that screen open, results still arrive as onSubmit / form-filling:submitted for the same session
Clinician closes the processing screen early	form-filling:closed fires; no onSubmit from that action. If they start a new session before late results arrive, those results may fire form-filling:background-submitted instead
Clinician cancels during selection or recording	onCancel and form-filling:cancelled; no structured data
Last form cannot be deselected	UI blocks deselecting the only remaining form during selection or recording

Refer to Session workflow for processing, cancel, and webhook delivery.

Next steps

Error handling example - React and JavaScript UI patterns.

Events - form-filling:error payload details.

Prerequisites - CSP, webhooks, and template setup.