> For the complete documentation index, see [llms.txt](https://docs.taptap3d.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.taptap3d.com/testing-and-support/troubleshooting.md). # Troubleshooting Diagnose local mock setup and proposed iframe, API, revision and search-content failures. Local mock failures can be diagnosed today. HTTP and iframe behaviour below describes the proposed live contract; it is not evidence that a production API exists. ## Local setup | Symptom | Check | Next action | | -------------------------------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------- | | `npm run demo` is missing | You are in the documentation repository root, with `package.json`. | Open the correct directory; the main application is a different repository. | | Port 8787 is already in use | Another process or earlier mock is listening. | Stop your own earlier mock or choose an available port in your local copy. | | Connection refused | The mock is running and the browser uses `http://127.0.0.1:8787`. | Start `npm run demo`. Use HTTP for loopback. | | Example domain fails | You copied `api.example.com` or `embed.example.com`. | Use the local mock; those domains are placeholders. | | Requested Chinese but received English | The mock contains only the English fixture. | Check `language: en`; this is the intended truthful fallback. | The mock has no database, signup or credential step. Do not connect it to real inventory or publish it as a service. ## API response | Status | What to check | Action | | ---------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | | `400` | Parameter names, locale values, duplicate parameters and ID encoding. | Correct the request. Do not repeat it unchanged. | | `404` | Public publication ID and, if supplied, the approved revision. | Confirm the mapping with the record owner. A private or unapproved record must remain unavailable. | | `410` | Whether the publication was withdrawn. | Remove content, including pinned copies; do not fall back to a cached revision. | | `429` | `Retry-After` and request frequency. | Delay requests. Exact service quotas still need definition. | | `503` or timeout | Network/service availability. | Show fallback content; avoid an unbounded retry loop. | See [Listing contract](/proposed-reference/listing-contract.md) for machine-readable error codes. The mock demonstrates `400`, `404` and `410`; it does not simulate quotas or service outages. ## Frame does not load Inspect the browser console and network request. Check the exact issued embed origin, the host's `frame-src` policy, and the service's registered parent-origin policy. A JSON CORS change does not fix iframe framing restrictions. If script execution is blocked, bundle the host script through the storefront's approved mechanism. Do not disable its CSP or grant extra iframe permissions to silence an error. The local mock is same-origin; production iframe behaviour still needs testing on the issued cross-origin service. ## Frame does not resize Check the message sender's origin and frame window, then its version, publication ID and integer height. Heights outside 240–1600 are ignored by the sample. A copied or forged event must not pass validation. See [Iframe lifecycle](/proposed-reference/host-integration.md). The 10-second loading timeout is a fallback notification, not proof of withdrawal. A valid late ready message clears it. ## Search page is empty Inspect the host's HTML response with scripts disabled. The iframe does not replace the host page's approved title and summary. A build-time snapshot also needs a refresh and withdrawal strategy. See [Search visibility](/integration-guides/search-visibility.md). ## Report an issue Email with the affected page, integration surface, browser/version, timestamp, HTTP status or error code, and steps to reproduce. A synthetic example is preferable to a customer record. Remove credentials, private values and personal information from headers or screenshots before sharing them. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.taptap3d.com/testing-and-support/troubleshooting.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.