> ## Documentation Index
> Fetch the complete documentation index at: https://developer.suki.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Form Filling SDK Error Handling

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

<div className="quick-summary-wrapper">
  <div className="quick-summary-header">
    <span className="quick-summary-icon" aria-hidden="true" />

    <span className="quick-summary-title">Quick summary</span>
  </div>

  <div className="quick-summary-content">
    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.

    <br />

    <br />

    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.
  </div>

  <div className="quick-summary-footer">
    <span className="quick-summary-footer-icon" aria-hidden="true" />

    <span className="quick-summary-footer-text">Last updated:</span>
    <span className="quick-summary-footer-date">July 2026</span>
  </div>
</div>

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](#blank-ui-with-no-error-code) below.

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

## 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](/form-filling-sdk/examples/error-handling) 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 JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
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](#blank-ui-with-no-error-code) below.
2. Verify that your `form_template_ids` are valid. See [Template ID issues](#template-id-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 HTML theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
<div id="suki-form-container" style="width: 100%; height: 600px;"></div>
```

In React, style the wrapper `FormFilling` renders:

```css CSS theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
.suki-form-filling {
  width: 100%;
  height: 600px;
}
```

<Tip>
  Refer to [Configuration](/form-filling-sdk/guides/configuration#container-sizing) for container sizing.
</Tip>

### 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](/form-filling-sdk/guides/authentication) and [Partner onboarding](/documentation/get-started/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.

<Warning>
  * 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.
</Warning>

| 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 |

<Note>
  Contact Suki's [Support team](mailto:support@suki.ai) to confirm staging and production `template_id` values. Refer to [Form filling templates](/documentation/concepts/form-filling/form-filling-templates) for supported assessment types.
</Note>

## 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](/form-filling-sdk/guides/integration-patterns) for processing, cancel, and webhook delivery.

## Next steps

<Icon icon="file-lines" iconType="solid" /> Refer to [Error handling example](/form-filling-sdk/examples/error-handling) for React and JavaScript UI patterns

<Icon icon="file-lines" iconType="solid" /> Refer to [Events](/form-filling-sdk/api-reference/events) for `form-filling:error` payload details

<Icon icon="file-lines" iconType="solid" /> Refer to [Prerequisites](/form-filling-sdk/prerequisites) for CSP, webhooks, and template setup