topic Upsert API error "Contact Already Exists" Conflict in APIs & Integrations

Upsert API error "Contact Already Exists" Conflict

BEvans87 — Fri, 14 Mar 2025 18:35:27 GMT

We are using /crm/v3/objects/contacts/batch/upsert to create/update contacts in HubSpot but it is returning the following.

"status": "error",
    "message": "Contact already exists. Existing ID: 106003670396",
    "correlationId": "c43303af-1247-4344-b955-32286ac77625",
    "category": "CONFLICT"

It will retry until it succeeds but how can we resolve these initial errors? Haven't found any documentation to resolve this.

Re: Upsert API error "Contact Already Exists" Conflict

Jaycee_Lewis — Mon, 17 Mar 2025 05:53:45 GMT

Hey, @BEvans87 👋 I don't believe you are missing any additional documentation. This is the expected behaviour for this endpoint. You are not the first community member to note this. We'll leave this open in case other community members have any strategies they use to work around this response.

Best,

Jaycee

Re: Upsert API error "Contact Already Exists" Conflict

NFreeman — Tue, 13 Jan 2026 18:15:26 GMT

We’re seeing the same issue on our end. @Jaycee_Lewis our understanding is that an upsert API call should update an existing contact when a matching identifier is provided. Can you confirm whether that’s expected behavior?

Additionally, the response is returning a status of 'error' (lowercase), which doesn’t appear to be documented in the API reference.

Re: Upsert API error "Contact Already Exists" Conflict

Victor_Becerra — Tue, 13 Jan 2026 19:42:53 GMT

Hi @NFreeman

Thanks for chiming in — totally fair question, and I can see why this feels contradictory when the endpoint is called “upsert.”

I’d like to invite a few Community members who are subject matter experts in the Contacts API and batch upsert behavior to join this conversation.
@Kevin-C @GRajput @evaldas — hope you’re all having a great week! Have you seen /crm/v3/objects/contacts/batch/upsert return CONFLICT “Contact already exists” as part of expected behavior, and if so, what’s the cleanest strategy to reduce/handle these initial “error” responses? Also curious if you’ve seen any clarification around the lowercase status: "error" response and how teams typically treat it (retry logic, pre-checks, alternate endpoint patterns, etc.).

Any insights would be greatly appreciated.
Best,
Victor

Re: Upsert API error "Contact Already Exists" Conflict

evaldas — Wed, 14 Jan 2026 14:30:03 GMT

@NFreeman makes a good point on the documentation. The value of "error" is not one of the status options that are listed as available, so the documentation may need to be updated.

Also, if the error happening on initial upsert is expected behavior, that should be included in the documentation as well.

Right now, the documentation states:

You can also batch create and update contacts at the same time using the upsert endpoint. For this endpoint, you can use email or a custom unique identifier property. Following the request, if the contacts already exist, they’ll be updated and if the contacts don’t exist, they’ll be created.