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

# Troubleshooting

> Common issues and solutions for ClickTerm SDK and API integrations.

This page covers the most common issues developers encounter when integrating ClickTerm. For error codes, see the [Error Reference](/dev/resources/errors).

## Clickwrap dialog not showing

<Steps>
  <Step title="Check template status">
    The template must be **Enabled** in the [dashboard](https://app.clickterm.com/templates). Disabled templates are not served by the SDK.
  </Step>

  <Step title="Check version state">
    The template must have a version in **Effective** state — not just Scheduled. Verify that the `effectiveAt` timestamp has passed.
  </Step>

  <Step title="Check prior acceptance">
    The SDK automatically suppresses the dialog if the user has already accepted the latest **major** version. This is expected behavior, not a bug.

    To verify, call `GET /clickwraps/{endUserId}/status` and check the status field. If it's `ACCEPTED`, the dialog won't appear until a new major version is published.
  </Step>

  <Step title="Verify SDK initialization">
    Ensure `ClicktermClient.initialize()` was called with the correct **App ID** before calling `ClicktermDialog.show()`.
  </Step>
</Steps>

## Verification returns 401 Unauthorized

| Check                   | What to do                                                                                |
| ----------------------- | ----------------------------------------------------------------------------------------- |
| Headers vs query params | Credentials must be sent as `X-APP-ID` and `X-APP-KEY` headers, **not** query parameters  |
| Correct App Key         | If you recently regenerated the App Key, update your backend with the new one             |
| Correct integration     | Make sure the App Key matches the App ID you're using (each integration has its own pair) |

## Events showing as "Unverified"

This means your backend hasn't called `POST /clickwrap/verify` yet. The SDK returns a Signature, but the event stays in `UNVERIFIED` state until your backend verifies it.

**Solution:** Ensure your frontend sends the Signature to your backend, and your backend calls the [verify endpoint](/dev/guides/verifying-signature).

## Template not found (404)

<Steps>
  <Step title="Template enabled?">
    Go to [Templates](https://app.clickterm.com/templates) and confirm the toggle is **on**.
  </Step>

  <Step title="Version effective?">
    Open the template and check the version's `effectiveAt` date. If it's in the future, the SDK can't fetch it yet.
  </Step>

  <Step title="App linked?">
    If you've linked templates to specific integrations, make sure the App ID you're using matches one that's linked to this template.
  </Step>
</Steps>

## Signature is null

A `null` Signature from `ClicktermDialog.show()` means the user has **already accepted** the latest major version. This is expected behavior.

```javascript theme={null}
ClicktermDialog.show({
  endUserId: "user-123",
  clickwrapTemplateId: "YOUR_TEMPLATE_ID",
}).then((result) => {
  if (result.clicktermSignature === null) {
    // User already accepted — proceed normally
    console.log("Already accepted, no action needed");
  } else {
    // New acceptance — send to backend
    sendToBackend(result.clicktermSignature);
  }
});
```

## Android SDK: dialog not appearing

| Check            | What to do                                                                                      |
| ---------------- | ----------------------------------------------------------------------------------------------- |
| Activity context | Pass a valid `Activity` context (not `ApplicationContext`) to `ClicktermDialog.show()`          |
| Initialization   | Call `ClicktermClient.initialize()` in your `Application` class or before showing the dialog    |
| Network          | Ensure the device has internet access — the SDK fetches template content from the ClickTerm API |

## React Native: iOS framework didn't download

The React Native SDK downloads the native iOS `ClicktermSDK.xcframework` from the ClickTerm CDN at install time — during `pod install`, with a best-effort prefetch right after `npm install`. It is **not** bundled in the npm package, so a failed download surfaces as a missing-framework link error in Xcode or an aborted `pod install`.

| Check                   | What to do                                                                                                                                                                       |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Network access          | The fetch needs HTTPS access to `cdn.clickterm.com`. On a VPN, proxy, or locked-down CI, allowlist that host.                                                                    |
| Re-run the fetch        | Restore connectivity, then run `cd ios && pod install` again — or fetch manually with `npm run fetch:xcframework` from the SDK package directory.                                |
| Skipped install scripts | Installing with `--ignore-scripts` (or pnpm's default script blocking) skips the prefetch. That's fine — `pod install` still fetches the framework, so make sure that step runs. |

This only affects iOS builds. Android resolves its native dependency from Maven Central and is unaffected.

## Rate limited (429)

If you receive `HTTP 429`, you've exceeded the rate limit. Read the `Retry-After` header and wait before retrying.

See [Rate Limits](/dev/resources/rate-limits) for retry code examples and best practices.

## Still stuck?

If none of the above resolves your issue:

1. Check the [Error Reference](/dev/resources/errors) for the specific error code
2. Review the [FAQ](/product/reference/faqs) for common questions
3. Contact support through the [ClickTerm Dashboard](https://app.clickterm.com)