> ## Documentation Index
> Fetch the complete documentation index at: https://the-early-spring18.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshoot Common Issues with the Google Platform

> Diagnose and fix common issues with authentication errors, search not returning results, webhook delivery failures, and integration problems.

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](/help/support) 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:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.google.com/v1/search \
    -H 'Authorization: Bearer YOUR_API_KEY'
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.google.com/v1/search",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
  )
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.google.com/v1/search", {
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
    },
  });
  ```
</CodeGroup>

**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:

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Webhook Not Firing

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

<Steps>
  <Step title="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](https://ngrok.com) during local development to expose a local server to the internet.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Warning>
  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.
</Warning>

## 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.

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Note>
  For a complete walkthrough of setting up and configuring integrations, including scope requirements for each supported provider, see the [Integrations guide](/guides/integrations).
</Note>

## 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.

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Tip>
  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.
</Tip>