Troubleshooting

Practical fixes for the most common Vanta integration problems.

Events not appearing

Symptom: events are tracked but do not show up in the dashboard.

Likely cause: the key is wrong, the request was rejected, or the event is still in the ingestion queue.

Check the call returned 202 Accepted. Anything else means the event was not accepted.
Verify the API key is active and belongs to the project you are viewing.
Ingestion enqueues events for the worker to process, so there is a short delay before they appear.
Confirm the event type does not start with $ and was not rejected during validation.

Symptom: requests fail with HTTP 429.

Likely cause: you exceeded the per-key window for the endpoint.

Single ingestion allows 1000 events/min; batch ingestion allows 100 requests/min.
Back off for the seconds in the Retry-After response header, or the retryAfter value on RateLimitError.
Prefer batch ingestion over many single calls; it cuts request count dramatically.

Symptom: requests fail with 401 or 403.

Likely cause: a missing or wrong API key, a revoked key, or a session without the required role.

Confirm the request sends Authorization: Bearer vk_....
The full key secret is shown only once at creation time. If it is lost, create a new key.
A 403 on admin routes means the session is not an owner or admin for the project.
Keys are scoped to one project; a key for another project cannot read this one.

Symptom: analytics results are empty, or the server rejects the query.

Likely cause: a malformed or non-UTC time range, or one with the bounds reversed.

Symptom: a filtered query returns fewer events than expected.

Likely cause: the field path or operator does not resolve the way the query expects.

Use the documented aliases: userId, groupId, sourceId, projectId, createdAt, and event for type.
Nested event properties need the data. prefix, such as data.plan; context paths need context..
AND/OR nesting deeper than 5 levels is rejected. Keep the tree shallow.
Filters are case-sensitive for exact matches; use contains for partial matches.

Symptom: a monitor reports down even though the service is running.

Likely cause: the heartbeat is not arriving within the expected interval plus grace period.

Confirm the heartbeat endpoint is being called with the correct monitor slug.
A monitor flips to down only after the interval plus the grace period passes without a heartbeat.
If deliveries lag, increase the grace period so brief pauses do not page you.
The first heartbeat creates the monitor if it does not exist; a new monitor reports unknown until then.

Symptom: your endpoint never receives a delivery, or deliveries fail.

Likely cause: a permanent 4xx response, an unreachable URL, or signature verification failing on your side.

Server errors and network failures retry after roughly 30s, 2m, 10m, and 30m, up to 5 attempts.
Any other 4xx is treated as permanent; the delivery is not retried.
Each request times out after 10 seconds, so the endpoint must answer quickly.
URLs must be publicly reachable; localhost and private address ranges are rejected at creation.
Verify signatures over the raw body with HMAC-SHA256 and reject deliveries older than five minutes.

Symptom: a published page at /p/:slug returns nothing or an error.

Likely cause: the page is not published, the slug is wrong, or the page route is being blocked.

Confirm the page was published and the slug matches the published URL.
Published pages are intentionally public: they load without a session.
Management routes (create, update, publish, unpublish) require an owner or admin session with requireProjectAdmin.