HubSpot breaking changes, updated weekly

Every verified HubSpot trap in Footgun: changes and behaviors that break code or give wrong results, newest first. Each one has the error you see, the fix, and the date it was last checked. The list updates when the weekly check adds or retires a trap. For the full cause and sources, open the trap, or see all HubSpot traps.

1. fg-0388· added 2026-10-15· last checked 2026-10-15

   HubSpot GET contact by email returns 404 even though the contact exists

   Symptom

   404 from /crm/v3/objects/contacts/jane@example.com

   Fix

   Pass idProperty=email on single and batch reads, and for upserts that only touch some properties use a custom unique property as the key.

2. fg-0389· added 2026-10-15· last checked 2026-10-15

   HubSpot lifecyclestage will not move back to an earlier stage through the API

   Symptom

   lifecyclestage keeps the later value after an API update

   Fix

   Send two updates: first set lifecyclestage to an empty string, then set the earlier stage. Read the record back to confirm.

3. fg-0391· added 2026-10-15· last checked 2026-10-15

   HubSpot returns 429 RATE_LIMIT with policyName TEN_SECONDLY_ROLLING or DAILY

   Symptom

   429 with "policyName":"TEN_SECONDLY_ROLLING"

   Fix

   Read X-HubSpot-RateLimit-Remaining and pause when it is low, use batch endpoints for bulk work, and treat a DAILY 429 as a stop until the reset rather than retrying.

4. fg-0385· added 2026-10-15· last checked 2026-10-15

   hubspot-api-client raises AttributeError: 'HTTPResponse' object has no attribute 'getheader'

   Symptom

   AttributeError: 'HTTPResponse' object has no attribute 'getheader'

   Fix

   Exclude urllib3 2.6.0 in your requirements and upgrade to 2.6.1 or later.

5. fg-0386· added 2026-10-15· last checked 2026-10-15

   HubSpot batch create results come back in a different order than the inputs

   Symptom

   results[i] does not correspond to inputs[i]

   Fix

   Match each result back on a unique property you sent, such as email or your own unique id property, never by array index. Add an objectWriteTraceId per input so partial failures come back as a 207 with per-input errors, and chunk inputs into groups of 100.

6. fg-0387· added 2026-10-15· last checked 2026-10-15

   HubSpot CRM search returns 400 once paging passes 10,000 results

   Symptom

   HTTP 400 when after is 10000 or higher

   Fix

   Page with a keyset instead of the cursor: sort ascending by hs_object_id, remember the last id, and start a new query with hs_object_id GT that id whenever you near the cap. For full exports use the list or batch read endpoints instead of search.

7. fg-0390· added 2026-10-15· last checked 2026-10-15

   HubSpot rejects a dropdown value with 'Property values were not valid'

   Symptom

   400 Property values were not valid

   Fix

   Read the property definition and map labels to option values before writing, or add the missing option to the property.

8. fg-0393· added 2026-10-15· last checked 2026-10-15

   HubSpot search calls hit 429 even though the app is far under its 10-second limit

   Symptom

   429 with errorType RATE_LIMIT from /crm/v3/objects/*/search

   Fix

   Throttle search calls to at most four per second per portal with a dedicated limiter, and retry 429 with backoff. Prefer batch read by id when you already know the records.

9. fg-0394· added 2026-10-15· last checked 2026-10-15

   HubSpot search fails with VALIDATION_ERROR when a query has too many filters

   Symptom

   400 VALIDATION_ERROR from the search endpoint

   Fix

   Collapse equality filters on one property into a single IN filter, split very wide queries into several requests and merge the results, and keep one sort rule.

10. fg-0395· added 2026-10-15· last checked 2026-10-15

    HubSpot search misses a record created seconds earlier, so dedupe logic creates duplicates

    Symptom

    Search returns total 0 for a contact created moments before

    Fix

    Do not use search as the source of truth for existence checks right after a write. Look up by a unique property with idProperty, use batch upsert, or keep the id returned by the create call.

11. fg-0396· added 2026-10-15· last checked 2026-10-15

    HubSpot settings no longer offer Create a private app, so setup guides dead-end

    Symptom

    No Create a private app button under Settings, Integrations

    Fix

    For a new in-account integration, create a Service Key under Settings, Integrations, Service Keys, or build a 2026.09 developer platform project. Keep existing private app tokens and rotate them as before.

12. fg-0397· added 2026-10-15· last checked 2026-10-15

    HubSpot webhook handler processes the same event twice or in the wrong order

    Symptom

    Same objectId and subscriptionType delivered more than once

    Fix

    Acknowledge with 200 immediately and process from a queue, dedupe on eventId, and order by occurredAt instead of arrival time.

13. fg-0398· added 2026-10-15· last checked 2026-10-15

    HubSpot X-HubSpot-Signature-v3 check fails even with the right client secret

    Symptom

    Computed HMAC never equals X-HubSpot-Signature-v3

    Fix

    Rebuild the exact public URL HubSpot called, decode only the listed characters, use the raw body string, base64 the HMAC keyed with the app client secret, compare in constant time, and check the timestamp is under five minutes old.