Errors

All inbound webhook endpoints return standard HTTP status codes. Error bodies are JSON.

Error codes

Status	Meaning	Common cause
`400`	Bad request	Missing required fields — e.g. no identifiers on a find request, no `contact_id` on update
`401`	Unauthorized	Token is invalid, not found, or the webhook has been disabled by an org admin
`404`	Not found	Unknown path under `/contacts`, or contact not found on an update request
`405`	Method not allowed	Request was not a `POST`
`500`	Internal server error	Handler threw before sending a response body

All errors return a JSON body with an error field:

{
  "error": "Unauthorized"
}

{
  "error": "Provide at least one of full_name, phone_number, contact_email"
}

For async endpoints (create-with-ai, create), validation happens in the background worker — not at the HTTP layer. This means:

A 200 response does not guarantee a contact was created
If unstructured_text is empty, no contact work is performed despite a successful response
If none of full_name, phone_number, or contact_email are present on a structured create, the worker returns early without creating

Do not treat a 200 on an async endpoint as confirmation that a contact exists. If you need to verify creation, follow up with a find request.

Async endpoints deduplicate payloads using a hash of the request body. If the same payload is received more than once:

This is not an error — it is expected behavior. Use the presence of eventId to distinguish new events from duplicates.