# Common Issues

## Connection issues

<details>

<summary>Invalid API token error on connection</summary>

Double-check that you copied the full API token without any trailing spaces. In Zendesk Chat, go to **Settings → Account → API** and regenerate the token if needed. Also confirm you're using the correct subdomain — it should match exactly what appears in your Zendesk Chat URL.

</details>

<details>

<summary>Wrong subdomain format causing authentication failure</summary>

Your subdomain should be just the prefix before `.zendesk.com` — for example, if your URL is `acme.zendesk.com`, enter `acme`. Do not include `https://` or `.zendesk.com` in the subdomain field.

</details>

## Missing data

<details>

<summary>Chats or Agent timelines returning no data</summary>

Check that you've set a start date using the date picker. The **Chats** and **Agent timelines** entities require a start date — without one, the export may return empty results. Set the start date to a period when you know chat activity occurred.

</details>

<details>

<summary>CSAT rating field is empty for all chats</summary>

The `rating` field only populates when CSAT surveys are enabled in your Zendesk Chat account and when visitors actually submit a rating. If CSAT is disabled or visitors didn't respond, this field will be blank. Check your CSAT settings under **Settings → Chat → Satisfaction**.

</details>

<details>

<summary>Some agents missing from the Agents export</summary>

Deactivated or deleted agents may not appear in the Agents entity. If you need historical data for former agents, look for their IDs in the Chats entity — agent\_ids are preserved even after an agent is removed.

</details>

## Permission errors

<details>

<summary>403 Forbidden when pulling certain entities</summary>

Some entities — particularly Roles, Routing settings, and Account — require Admin-level access. If your API token belongs to an Agent-role user, you'll get a 403 on restricted endpoints. Generate the API token from an Admin account to resolve this.

</details>

<details>

<summary>Bans entity returns empty results</summary>

Accessing the Bans entity requires Admin permissions. If the entity returns empty results but you know bans exist, check that the token owner has Admin rights in Zendesk Chat.

</details>

## Data discrepancies

<details>

<summary>Chat counts in Coupler.io don't match the Zendesk Chat dashboard</summary>

Zendesk Chat dashboards often include offline messages alongside live chats. In the Chats entity, filter by the `type` field — `chat` for live conversations and `offline_msg` for messages left when no agents were available. Make sure both types are accounted for in your comparison.

</details>

<details>

<summary>Duration values seem much larger than expected</summary>

The `duration` field is measured in seconds, not minutes. Divide by 60 in your spreadsheet or BI tool to convert to minutes. For example, a duration of 360 = 6 minutes.

</details>

## Rate limits

<details>

<summary>Data flow fails mid-run with a rate limit error</summary>

Zendesk Chat's API enforces rate limits that vary by plan. If you're exporting a large date range of Chats, try splitting the export into shorter time windows using the start date picker. Running large historical exports during off-peak hours can also reduce the chance of hitting limits.

</details>