← Back to home

Troubleshooting

Common issues and how to resolve them.

Event ingestion

I'm getting 401 Unauthorized on the events endpoint

  • Confirm your API key starts with zo_live_. Test keys are not accepted in production.
  • Pass the key as Authorization: Bearer zo_live_... in the header, not as a query parameter or in the request body.
  • Check that the key has not been revoked in your dashboard under API Keys.

I'm getting 402 Payment Required

You have exceeded your monthly event limit. Check your current usage in the dashboard under Billing. The response body includes your limit and current count:

{
  "error": "Monthly event limit exceeded",
  "limit": 1000,
  "current": 1000,
  "remaining": 0
}

Upgrade your plan or wait for the next billing cycle to resume sending events.

I'm getting 400 with validation errors

Check the errors array in the response for specifics. Common causes:

  • Missing eventName - every event needs a name
  • Missing both email and domain - at least one is required for matching
  • Invalid timestamp - must be ISO 8601 format (e.g., 2026-03-12T10:30:00Z)
  • More than 50 keys in properties
  • More than 100 events in a single batch (use /v1/events/bulk for larger batches)

Some events are accepted but show as rejected

A batch can partially succeed. Events are rejected (not retried) when they fail validation. Duplicate eventId values are also counted as rejected since they have already been recorded. Check the errors array and duplicateEventIds field in the response.

HubSpot sync

Events are accepted but not appearing in HubSpot

  1. Check sync timing. Free plan syncs once per day (up to 24h delay). Pro and Growth plans sync in near real-time.
  2. Verify you have a mapping. Events without a matching mapping are stored but not synced. Go to Mappings in the dashboard and confirm a mapping exists for your event name.
  3. Check the contact/company exists. The email or domain in your event must match an existing HubSpot record. Zoody does not create new contacts or companies.
  4. Check the Event Explorer. In the dashboard, go to Event Explorer to see your events, their match status, and any sync errors.

The HubSpot property shows the wrong value

  • Check your aggregation type. A "count" mapping counts events, not sums a property. If you want to total a numeric field, use "sum" with the correct source_field.
  • Check the time window. A 30-day rolling window only includes events from the last 30 days. Older events drop off. Use "all time" if you want a cumulative total.
  • Check the source_field spelling. For sum and last_value aggregations, the source_field must exactly match the key in your event properties. It is case-sensitive.

HubSpot connection lost or token expired

If you see a "HubSpot disconnected" error in the dashboard, your OAuth token may have been revoked or expired. Go to Settings in the dashboard and click "Reconnect HubSpot." This starts a new OAuth flow and refreshes the token. Your mappings and data are preserved.

I see 'Property not found' errors in the sync log

If you selected an existing HubSpot property that was later deleted, syncs will fail for that mapping. Either recreate the property in HubSpot or update the mapping to use a different property. If you are using a custom property name, Zoody auto-creates it on first sync - this error should not occur for custom properties unless HubSpot permissions have changed.

TypeScript SDK

Events are not being sent (no network requests)

The SDK batches events and flushes them on an interval (default: 5 seconds) or when the batch reaches 50 events. If your process exits before the flush, events are lost.

  • In serverless functions (Lambda, Vercel, etc.), always call await zoody.flush() before returning the response.
  • In long-running processes, add a shutdown handler: process.on("SIGTERM", () => zoody.shutdown())
  • Enable debug: true in the SDK config to see batch activity in the console.

Can I use Zoody without the SDK?

Yes. The SDK is optional. You can send events with a simple POST request from any language. See the API Reference for curl examples and the full endpoint spec. The SDK just adds convenience features like automatic batching and retries.

Mappings

I hit the mapping limit for my plan

Each plan has a maximum number of mappings: Free (3), Pro (25), Growth (unlimited). Multi-window mappings count as multiple mappings (one per window). To free up space, delete mappings you no longer need or upgrade your plan.

Can I map the same event to multiple properties?

Yes. You can create multiple mappings for the same event name with different aggregation types, time windows, or target properties. For example, map "login" to both a 7-day count and a last_timestamp.

What happens when I delete a mapping?

The mapping is removed and Zoody stops syncing that property. Events already stored are not deleted. The HubSpot property and its current values remain in HubSpot - Zoody does not clear property values on deletion.

General

Does Zoody create contacts or companies in HubSpot?

No. Zoody only updates existing records. If an event contains an email or domain that does not match any HubSpot record, the event is stored but the sync step is skipped. The event will sync if a matching record is created in HubSpot later.

What happens if Zoody goes down?

Your product is not affected. The API call from your backend is fire-and-forget. If Zoody is unavailable, the request fails silently (or returns a 5xx error if you check the response). Events sent while Zoody is down are not recorded. Your application continues to function normally.

Can I delete my data?

Yes. You can delete individual events from the Event Explorer, or delete all workspace data from Settings. Account deletion removes all associated data including events, mappings, and HubSpot tokens.

Still stuck?

Contact us or email support@zoody.io. Include your workspace ID and a description of the issue and we will help you debug it.