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

# Debug tracking

> Diagnose installation, attribution, delivery, identity, and duplicate-event problems.

Debug one layer at a time: installation, click capture, request delivery, then dashboard attribution.

## 1. Verify the installation

Open **Workspace settings -> Tracking**, find the saved hostname, and select **Verify**. Enter a deployed public page that contains the installation.

Verification reports:

* a missing Biqli installation;
* a missing or malformed `data-publishable-key`;
* a key belonging to another workspace;
* multiple installations on one page;
* a URL outside the allowed hostname rule;
* private or unsafe verification targets.

## 2. Check the click ID

After visiting a conversion-enabled short link, inspect the destination URL for `bq_id`. Then check the SDK:

```js theme={null}
Biqli.getClickId();
```

For package usage:

```ts theme={null}
biqli.getClickId();
```

If the result is `null`, confirm:

* the short link has conversions enabled;
* the destination received `bq_id`;
* the SDK loaded once;
* consent is granted;
* the cookie path and domain include this page;
* browser storage is available;
* a privacy tool did not block the script.

## 3. Inspect the network response

Find the failed tracking request in browser developer tools or server logs. Save the `X-Biq-Request-Id` header or `request_id` JSON field.

| Code                             | Meaning                                      | First action                                            |
| :------------------------------- | :------------------------------------------- | :------------------------------------------------------ |
| `invalid_token`                  | Key missing, invalid, revoked, or wrong type | Check the credential and environment                    |
| `origin_not_allowed`             | Browser origin does not match a saved rule   | Add the exact hostname and save                         |
| `tracking_disabled`              | Workspace conversion tracking is disabled    | Enable and save tracking                                |
| `client_click_tracking_disabled` | `trackClick()` is disabled                   | Enable it or use redirect attribution                   |
| `attribution_required`           | No eligible click or customer attribution    | Forward a valid `bq_id` first                           |
| `insufficient_scope`             | Secret key lacks `conversions.create`        | Grant **Conversions -> Write**                          |
| `resource_not_found`             | Resource is missing or belongs elsewhere     | Check workspace and public ID                           |
| `idempotency_conflict`           | Identifier reused with changed data          | Restore the original payload or use a new logical event |
| `validation_error`               | Request fields are invalid                   | Read `error.details.errors`                             |

## 4. Check identity and money

* Reuse one `customerExternalId` for the same customer.
* Use a stable lead `eventId`.
* Use a stable sale `paymentProcessor` and `invoiceId`.
* Send amounts as integer minor units.
* Do not send historical `occurredAt` values outside the accepted window.

## 5. Confirm the dashboard

Open **Customers** and select the customer. Confirm:

* the click and event appear once;
* the attribution link is correct;
* the source matches the integration;
* lead and sale totals are correct;
* revenue uses the expected currency conversion;
* deleted links retain their historical snapshot.

## When contacting support

Include the request ID, approximate UTC time, endpoint, SDK name and version, and non-sensitive error code. Never send an API key, signing secret, cookie, or full unredacted customer payload.