Skip to main content
Most contact issues are duplicates, key scope, or plan limit.

​
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 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

​
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