Common errors
The errors integrations run into most often, and how to avoid them.
Contact must exist before its events
Events need an existing contact. An event for a contact that hasn't been created yet fails right away.
Create the contact first:
POST /users/update_or_create/: make sure the contact exists.POST /users-by-id/:user_custom_id/events/: then send the event.
Deals pointing to records that don't exist
Deals check every record they refer to: contacts, products, pipelines and stages. Common errors:
| Reference | Error message pattern |
|---|---|
user_id / user_custom_id | "object does not exist" / "does not exist" |
products / products_custom_id | "object does not exist" |
order_products → product_id | "Could not find product with id '...'" |
order_products → product_custom_id | "Could not find product with custom_id '...'" |
pipeline / stage | "object does not exist" |
status (invalid value) | "is not a valid choice" |
If a product reference fails, create the product with POST /products/, then retry the deal request.
Product not found on product events
Sync your product catalog before sending product events. If you still get a product-not-found error, create the product with POST /products/ and retry the event.
On /products-by-id/:custom_id/product_event/ the product is validated first. If it doesn't exist, you always get a 404, whatever else is in the request:
{"detail": "Couldn't find product with custom_id = 9999999"}
Once the product exists, the contact is validated:
| Scenario | Status | Error |
|---|---|---|
Non-existent user_id | 400 | "Client user with ID '999999' does not exist" |
Non-existent user_custom_id | 404 | "user for given user_id not found" |
Deals accept an empty request
The deals endpoint creates a deal even from an empty {} request, with default values (name: "", value: 0.00, status: 1). Check required fields on your side before sending.