Skip to main content
Even well-configured systems encounter hiccups from time to time. This guide walks you through the most common issues you might experience while using Google — from authentication failures and silent webhook drops to search queries that return nothing. For each problem you’ll find the most likely causes and the concrete steps needed to resolve them. Work through each section methodically, and if you’re still stuck after following the steps, contact our support team with your account ID and any relevant request IDs.

​
Authentication Errors

Authentication failures are usually caused by a missing, malformed, or insufficiently scoped API key. The HTTP status code in the response tells you exactly what’s wrong. 401 Unauthorized means your request arrived without a valid API key, or the key was not included in the expected header. Check that you are passing your key as a Bearer token in the Authorization header:
403 Forbidden means your API key is valid but lacks the permission scope required for the operation you’re attempting. Regenerate the key from Settings → API → Keys, making sure to select the correct scopes (for example, search:read for read-only search access, or data:write for creating and updating records). Replace the old key in your integration immediately after regenerating.

​
Search Returns No Results

If a search query returns an empty result set when you expect matches, work through these checks in order:
1

Check your query string for typos

Even a single misplaced character prevents a match. Copy the exact value of the record you’re looking for and paste it directly into the search query to rule out typos or encoding issues.
2

Allow time for indexing

Newly created or updated records take up to 30 seconds to appear in search results. If you’ve just added a record, wait a moment and retry. Bulk imports may require up to 2 minutes.
3

Review your active filters

Filters applied to a search — such as date ranges, tags, or record types — can silently exclude results that would otherwise match. Remove all filters temporarily and re-run the query to determine whether a filter is the culprit.
4

Confirm the data exists

Navigate directly to the record in the UI to verify it was saved successfully. If the record doesn’t exist, the search is working correctly; the issue is upstream in how the data was created.

​
Webhook Not Firing

If your registered webhook endpoint is not receiving events, work through the following checks:
1

Verify the endpoint is publicly reachable

Your webhook URL must be accessible from the public internet. Localhost URLs (http://localhost:…) and private network addresses will never receive deliveries. Use a tool like ngrok during local development to expose a local server to the internet.
2

Confirm the webhook is enabled

Navigate to Settings → Notifications and verify the toggle next to your webhook is in the Enabled state. Webhooks are not active by default after creation.
3

Inspect the delivery log

Open Settings → Webhooks → Delivery Log to view recent delivery attempts, including the HTTP status code returned by your endpoint and the full request/response payload. Failed attempts are highlighted in red and include error details.
4

Ensure your server responds within 10 seconds

Google considers a webhook delivery successful only when your endpoint returns a 2xx HTTP status within 10 seconds of delivery. If your server takes longer to process the event, acknowledge the delivery immediately and handle the processing asynchronously.
If your endpoint returns a non-2xx status code or times out, Google will retry delivery up to 5 times with exponential backoff over the following 24 hours. After 5 consecutive failures, the webhook is automatically disabled to protect your endpoint.

​
Integration Connection Failing

When a third-party integration loses its connection to Google, you’ll typically see authorization errors in the integration’s activity log.
1

Re-authorize the OAuth connection

Go to Settings → Integrations, find the affected integration, and click Reconnect. You’ll be redirected to the provider’s OAuth consent screen. Complete the authorization flow to issue a fresh access token.
2

Verify the API key has write scope

If the integration uses an API key rather than OAuth, confirm the key has the data:write scope. Read-only keys will cause silent failures for any operation that attempts to create or modify records.
For a complete walkthrough of setting up and configuring integrations, including scope requirements for each supported provider, see the Integrations guide.

​
Rate Limit Exceeded (429)

A 429 Too Many Requests response means your API key has sent more requests than your plan allows in the current 60-second rolling window.
1

Respect the Retry-After header

The 429 response includes a Retry-After header containing the number of seconds you must wait before sending another request. Honor this value in your retry logic rather than polling immediately, which would only extend the backoff period.
2

Cache search results client-side

For read-heavy workloads, cache the results of frequently repeated search queries on your side. Even a short cache TTL of 10–30 seconds can dramatically reduce your request volume without affecting the user experience.
3

Review your plan limits

If you’re regularly hitting the rate limit, your workload may have outgrown your current plan. Review your usage from Settings → Usage and consider upgrading to a higher plan with a larger request allowance.
When contacting support about any of the issues above, include your account ID (found in Settings → Account) and the X-Request-Id value from the failing API response headers. These two pieces of information let our team locate the exact request in our logs within seconds, drastically reducing the time to resolution.