> ## 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 — Contatos

> Erros comuns ao criar, atualizar e importar contatos no CRM.

<Tip>
  A maioria dos problemas em contatos é **duplicata**, **escopo da chave** ou **limite do plano**.
</Tip>

## 409 — Contato já existe

**Causa:** e-mail, telefone ou identificador externo já cadastrado no workspace.

**O que fazer:**

1. `GET /v1/contacts` com filtro por e-mail ou telefone
2. Atualize com `PUT /v1/contacts/{id}` em vez de novo `POST`
3. Na importação, use modo **upsert** se disponível

***

## 403 — Sem permissão

**Causa:** API Key sem o escopo necessário (`contacts:read`, `contacts:create`, etc.).

**O que fazer:** revise [Escopos da API Key](/contacts-api/como-funciona/escopos-da-api-key) e recrie ou edite a chave no painel.

***

## 403 — `PLAN_LIMIT_CRM`

**Causa:** limite de contatos ou recurso CRM do plano atingido.

**O que fazer:** upgrade de plano ou limpe contatos obsoletos (conforme política do workspace).

***

## 400 — Canal inválido

**Causa:** `channels` com tipo não suportado ou sem identificador (e-mail sem `@`, telefone sem DDI).

**O que fazer:** normalize telefone (E.164) e valide e-mail antes do `POST`.

***

## Tag ou tópico não aparece no contato

**Causa:** `tagIds` com ID errado; tópico só via preferências ou campo específico.

**O que fazer:**

* Liste tags: `GET /v1/tags`
* Confirme `PUT` com `tagIds` e escopo `contacts:update`
* Para tópicos, use link de preferências ou fluxo de opt-in documentado em [Tópicos](/contacts-api/como-funciona/topicos-de-comunicacao)

***

## Timeline vazia

**Causa:** contato novo; eventos ainda não sincronizados; falta `contacts:read` em sub-recursos.

**O que fazer:** envie mensagem de teste; aguarde webhook; confira `GET /v1/contacts/{id}/timeline`.

***

## Próximos passos

* [Quick Start](/contacts-api/como-funciona/quick-start)
* [Supressões — troubleshooting](/suppressions-api/como-funciona/troubleshooting)