Form Filling SDK Error Handling

Quick summary

This page helps you fix common Form filling SDK problems, such as a blank iframe, invalid template IDs, or sign-in failures. The SDK reports four error codes through SukiFormFillingError. Check code and reason in your handler, not message text alone.

Some issues never emit an error code, including a container with no height or a CSP block on the SDK iframe. Work through layout, template IDs, partner credentials, and HTTPS before you retry the session.

Last updated:July 2026

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`	`form_template_ids` is an empty array	Pass at least one `template_id` UUID
`SUKI_FF_001`	`unsupported-template-ids`	No IDs matched Suki’s template list	Confirm enabled `template_id` values with Suki support
`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	Show retry; check microphone permission and network

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:

Verify that the container has a height. See Blank UI below.
Verify that your form_template_ids are valid. See Template ID issues below.
Verify that partnerId and partnerToken are configured correctly through SukiAuthManager.
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 ID issues

Before the iframe opens, FormFillingClient.start() validates form_template_ids against Suki’s Medical form template catalogue.

Template IDs are different for staging and production environments.
Unsupported IDs are dropped before the UI opens. If at least one ID is valid, the session continues with the valid IDs only.
If no IDs remain after validation, the SDK emits SUKI_FF_001 (unsupported-template-ids) and does not open the UI.

Symptom	Likely cause
Immediate `SUKI_FF_001` (`empty-template-ids`)	`form_template_ids` is an empty array
Immediate `SUKI_FF_001` (`unsupported-template-ids`)	No IDs matched your partner account
Fewer forms than you passed	Some IDs were invalid and were dropped
`SUKI_FF_003`	Template list could not be loaded during validation

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

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

Refer to Error handling example for React and JavaScript UI patterns Refer to Events for form-filling:error payload details Refer to Prerequisites for CSP, webhooks, and template setup

Get Started

Integration Guides

Concepts & Feature Guides

API Reference

Resources

Form Filling SDK Error Handling

Choose the right error event

Form filling SDK error codes

SUKI_FF_004 messages

Troubleshooting Form filling issues

Blank UI with no error code

Checking container height

Checking CSP

Checking partner credentials

Checking HTTPS and microphone

Template ID issues

Handling normal session outcomes

Next steps

​Choose the right error event

​Form filling SDK error codes

​SUKI_FF_004 messages

​Troubleshooting Form filling issues

​Blank UI with no error code

​Checking container height

​Checking CSP

​Checking partner credentials

​Checking HTTPS and microphone

​Template ID issues

​Handling normal session outcomes

​Next steps

Choose the right error event

Form filling SDK error codes

SUKI_FF_004 messages

Troubleshooting Form filling issues

Blank UI with no error code

Checking container height

Checking CSP

Checking partner credentials

Checking HTTPS and microphone

Template ID issues

Handling normal session outcomes

Next steps