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

# Troubleshooting — Contacts

> Common errors when creating, updating, and importing contacts in the CRM.

<Tip>
  Most contact issues are **duplicates**, **key scope**, or **plan limit**.
</Tip>

## 409 — Contact already exists

**Cause:** email, phone, or external identifier already registered in the workspace.

**What to do:**

1. `GET /v1/contacts` with filter by email or phone
2. Update with `PUT /v1/contacts/{id}` instead of a new `POST`
3. On import, use **upsert** mode if available

***

## 403 — No permission

**Cause:** API Key missing the required scope (`contacts:read`, `contacts:create`, etc.).

**What to do:** review [API Key scopes](/en/contacts-api/como-funciona/escopos-da-api-key) and recreate or edit the key in the dashboard.

***

## 403 — `PLAN_LIMIT_CRM`

**Cause:** contact or CRM resource limit for the plan reached.

**What to do:** upgrade the plan or clean up obsolete contacts (per workspace policy).

***

## 400 — Invalid channel

**Cause:** `channels` with unsupported type or missing identifier (email without `@`, phone without country code).

**What to do:** normalize phone (E.164) and validate email before `POST`.

***

## Tag or topic not showing on contact

**Cause:** `tagIds` with wrong ID; topic only via preferences or specific field.

**What to do:**

* List tags: `GET /v1/tags`
* Confirm `PUT` with `tagIds` and `contacts:update` scope
* For topics, use the preferences link or opt-in flow documented in [Topics](/en/contacts-api/como-funciona/topicos-de-comunicacao)

***

## Empty timeline

**Cause:** new contact; events not yet synced; missing `contacts:read` on sub-resources.

**What to do:** send a test message; wait for webhook; check `GET /v1/contacts/{id}/timeline`.

***

## Next steps

* [Quick Start](/en/contacts-api/como-funciona/quick-start)
* [Suppressions — troubleshooting](/en/suppressions-api/como-funciona/troubleshooting)