Google Maps API 403 Forbidden & Timeout Errors: Complete Troubleshooting Guide

Understanding Google Maps API 403 and Timeout Errors

The Google Maps Platform returns HTTP 403 Forbidden when the request cannot be authorized. This is distinct from HTTP 401 (missing credentials) — 403 means credentials were presented but rejected. The JSON error body typically looks like:

{
  "error": {
    "code": 403,
    "message": "The caller does not have permission",
    "status": "PERMISSION_DENIED"
  }
}

For client-side Maps JavaScript API, the browser console shows:

Google Maps JavaScript API error: RefererNotAllowedMapError
Google Maps JavaScript API error: ApiNotActivatedMapError
Google Maps JavaScript API error: BillingNotEnabledMapError

Timeouts manifest differently: the HTTP response status is 200 but the JSON body contains "status": "OVER_QUERY_LIMIT", or the network request simply hangs until the browser or server timeout fires.

Step 1: Identify the Exact Error

Browser DevTools (Maps JavaScript API)

Open Chrome DevTools → Console. Google Maps injects descriptive error codes directly into the console. Copy the exact error code (e.g., RefererNotAllowedMapError) and cross-reference the Maps JavaScript API error codes reference.

Server-side / REST API calls

Capture the raw HTTP response:

curl -v "https://maps.googleapis.com/maps/api/geocode/json?address=New+York&key=YOUR_API_KEY" 2>&1 | grep -E '(HTTP|error|status|message)'

A 403 response will show:

< HTTP/2 403
{"error":{"code":403,"message":"API keys with referer restrictions cannot be used with this API.","status":"PERMISSION_DENIED"}}

Step 2: Check GCP Project Billing

This is the single most common cause of sudden 403 errors — the free trial expires or a billing account is detached.

1. Open console.cloud.google.com and select your project.
2. Navigate to Billing in the left sidebar.
3. Confirm a billing account is linked and the account is active (not suspended).
4. If billing is disabled, click Link a billing account and follow the prompts.

After re-enabling billing, Maps API calls typically resume within 5 minutes without any code changes.

Step 3: Verify the API Is Enabled

Each Maps Platform product (Maps JavaScript API, Geocoding API, Places API, Directions API, etc.) must be individually enabled.

1. In GCP Console go to APIs & Services → Library.
2. Search for the specific API you're calling (e.g., "Geocoding API").
3. Click it — if the button says Enable, click it. If it says Manage, it's already enabled.

Alternatively via gcloud:

# List enabled APIs
gcloud services list --enabled --project=YOUR_PROJECT_ID | grep maps

# Enable Geocoding API
gcloud services enable geocoding-backend.googleapis.com --project=YOUR_PROJECT_ID

# Enable Maps JavaScript API
gcloud services enable maps-backend.googleapis.com --project=YOUR_PROJECT_ID

Step 4: Audit API Key Restrictions

Go to APIs & Services → Credentials and click your API key.

HTTP referrer restrictions (browser keys)

If you see restrictions like https://example.com/*, the key will 403 for:

• http://example.com (wrong scheme)
• https://www.example.com (www prefix not listed)
• https://staging.example.com (subdomain not listed)
• localhost:3000 (local dev not listed)

Add all needed patterns:

https://yourdomain.com/*
http://yourdomain.com/*
https://www.yourdomain.com/*
https://staging.yourdomain.com/*
http://localhost/*

IP address restrictions (server keys)

For server-side API calls, the outbound IP of your server must be listed. Find your server's IP:

curl -s https://api.ipify.org
# or on the server itself:
whoami && curl -s ifconfig.me

Add that IP (or CIDR range) to the key's IP restriction list in GCP Console.

API restriction mismatch

If the key has an API restriction (only allowed to call specific APIs) and you're calling an API not in that list, you get 403. Either add the API to the restriction list or use a key with no API restriction.

Step 5: Rotate the API Key (if compromised)

If your key was exposed in a public repository or logs, revoke it and create a new one:

# Using gcloud
gcloud alpha services api-keys delete KEY_ID --project=YOUR_PROJECT_ID

# Create new key
gcloud alpha services api-keys create \
  --display-name="Maps Production Key" \
  --allowed-referrers="https://yourdomain.com/*" \
  --api-target=service=maps-backend.googleapis.com \
  --project=YOUR_PROJECT_ID

Update the key in your app config/secrets manager and redeploy.

Step 6: Fix Timeout and OVER_QUERY_LIMIT Errors

The OVER_QUERY_LIMIT status means you've exceeded the requests-per-second (RPS) rate for your quota tier. The default is 50 QPS for most APIs on a paid account.

Check current quota usage:

# View quota metrics in GCP
gcloud monitoring metrics list --filter="metric.type=serviceruntime.googleapis.com/quota/rate/net_usage" 2>/dev/null
# Easier: GCP Console → APIs & Services → Quotas

Implement exponential back-off (Node.js example):

async function geocodeWithBackoff(address, maxRetries = 5) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const res = await fetch(
      `https://maps.googleapis.com/maps/api/geocode/json?address=${encodeURIComponent(address)}&key=${process.env.GOOGLE_MAPS_API_KEY}`
    );
    const data = await res.json();

    if (data.status === 'OK') return data;
    if (data.status === 'OVER_QUERY_LIMIT') {
      const delay = Math.pow(2, attempt) * 1000 + Math.random() * 500;
      console.warn(`OVER_QUERY_LIMIT — retrying in ${delay}ms (attempt ${attempt + 1})`);
      await new Promise(r => setTimeout(r, delay));
      continue;
    }
    throw new Error(`Geocoding failed: ${data.status} — ${data.error_message || ''}`);
  }
  throw new Error('Max retries exceeded for geocoding request');
}

Request a quota increase:

If legitimate traffic exceeds defaults, go to APIs & Services → Quotas, select the quota line (e.g., "Geocoding API — Requests per day"), and click Edit Quotas to submit a quota increase request to Google.

Step 7: Validate the Fix End-to-End

# Test geocoding from the server that will make the call
curl -s "https://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Parkway&key=YOUR_KEY" | python3 -m json.tool | grep -E '(status|formatted_address)'

# Expected output:
# "status": "OK",
# "formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA"

If you still see 403, double-check that the curl command runs from the same IP/server environment that production uses (not your laptop).