Google Maps API 403 Error: Fix REQUEST_DENIED, ApiNotActivatedMapError & Timeouts

Understanding Google Maps API 403 Errors

A 403 Forbidden from a Google Maps API endpoint means the server understood your request but refuses to fulfil it due to an authorization problem — not a missing resource (404) and not a server crash (5xx). Google wraps this in a JSON envelope:

{
  "error": {
    "code": 403,
    "message": "The provided API key is invalid.",
    "status": "PERMISSION_DENIED"
  }
}

For the JavaScript Maps SDK loaded in a browser you will instead see a console error such as:

Google Maps JavaScript API error: ApiNotActivatedMapError
https://developers.google.com/maps/documentation/javascript/error-messages#api-not-activated-map-error

or:

Google Maps JavaScript API warning: NoApiKeys
Google Maps JavaScript API error: RefererNotAllowedMapError

The status field in the REST response (or the error code suffix in the JS API) is your primary diagnostic signal.

Step 1: Reproduce and Capture the Raw Error

Before changing anything, get the exact error body so you are fixing the right problem.

For REST / Places / Geocoding / Directions APIs:

curl -s "https://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Pkwy&key=YOUR_API_KEY" | python3 -m json.tool

Expected 403 response bodies and what they mean:

For the JavaScript Maps API, open DevTools → Network tab, filter by maps.googleapis.com, and look at the response body of the js?key=... request.

Step 2: Verify Billing Is Enabled

This is the single most common cause for projects created after June 2018.

1. Go to console.cloud.google.com/billing.
2. Ensure a billing account is linked to the project that owns the key.
3. A linked billing account does not mean you will be charged immediately — Google provides a $200/month free tier for Maps.

You can also check via gcloud:

gcloud beta billing projects describe YOUR_PROJECT_ID --format='value(billingEnabled)'
# Expected: True

Step 3: Confirm the Correct API Product Is Enabled

Each Maps product (Geocoding, Directions, Places, Maps JavaScript API, Static Maps, etc.) must be individually enabled in the API Library.

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

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

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

# Enable the Places API
gcloud services enable places-backend.googleapis.com --project=YOUR_PROJECT_ID

Common API service names:

Step 4: Audit API Key Restrictions

Key restrictions are the second most common cause of a 403 that "works in one place but not another."

# View current restrictions on your key (requires project owner role)
gcloud alpha services api-keys describe YOUR_KEY_ID --project=YOUR_PROJECT_ID

HTTP Referrer restrictions (browser-side key):

If your key has referrer restrictions set to https://yourdomain.com/* but you are testing from localhost:3000, the API will return 403. Add localhost as an allowed referrer during development:

Allowed referrers:
  http://localhost:3000/*
  https://yourdomain.com/*
  https://www.yourdomain.com/*

Note: referrer restrictions do not work for server-side calls because Node.js / Python / curl do not send a Referer header. Server-side calls must use an IP address restriction or an unrestricted key stored in a secret manager.

IP address restrictions (server-side key):

# Find your outbound IP
curl -s https://api.ipify.org
# Add that IP (or CIDR range) to the key's IP restrictions in Cloud Console

Step 5: Diagnose Timeout Errors

Timeout errors (ETIMEDOUT, net::ERR_TIMED_OUT, or a 408/504 returned by a proxy) have different root causes:

5a. QPS (Queries Per Second) rate limiting:

The Maps Geocoding API has a default limit of 50 QPS. If you spike above that, subsequent requests queue and eventually time out on the client side even though the server would eventually respond with OVER_QUERY_LIMIT.

# Check current quota usage
gcloud monitoring metrics list --filter='metric.type=serviceruntime.googleapis.com/api/request_count' 2>/dev/null
# Or inspect in Cloud Console: APIs & Services → Maps API → Quotas

Add exponential backoff in your code:

import time, requests
from random import uniform

def geocode_with_backoff(address, api_key, max_retries=5):
    url = "https://maps.googleapis.com/maps/api/geocode/json"
    for attempt in range(max_retries):
        resp = requests.get(url, params={"address": address, "key": api_key}, timeout=10)
        data = resp.json()
        if data["status"] == "OK":
            return data
        if data["status"] == "OVER_QUERY_LIMIT":
            wait = (2 ** attempt) + uniform(0, 1)
            time.sleep(wait)
            continue
        raise RuntimeError(f"Maps API error: {data['status']} — {data.get('error_message', '')}")
    raise RuntimeError("Max retries exceeded")

5b. Client-side fetch timeout too short:

The Maps JavaScript API loader can take 1–3 seconds on a cold load. If your wrapper sets a 1-second timeout, it will fail intermittently on slower connections.

// Too aggressive:
const mapPromise = Promise.race([
  loadGoogleMaps(),
  new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), 1000))
]);

// Better — 10 seconds for initial load:
const mapPromise = Promise.race([
  loadGoogleMaps(),
  new Promise((_, reject) => setTimeout(() => reject(new Error('Maps load timeout')), 10000))
]);

5c. Verify the endpoint is reachable from your network:

curl -v --max-time 10 "https://maps.googleapis.com/maps/api/geocode/json?address=test&key=YOUR_KEY"
# Look for: * Connected to maps.googleapis.com
# If it hangs: check firewall rules, DNS resolution, or proxy configuration

# DNS check:
nslookup maps.googleapis.com
dig maps.googleapis.com +short

Step 6: Rotate and Harden Your Key

If you cannot determine which restriction is causing the 403, the fastest way to isolate the issue is to create a temporary unrestricted key:

gcloud alpha services api-keys create --display-name='debug-maps-key' --project=YOUR_PROJECT_ID
# Note the key string from the output, test with it
# If it works: the problem was a restriction on your original key
# Delete the debug key immediately after testing:
gcloud alpha services api-keys delete DEBUG_KEY_ID --project=YOUR_PROJECT_ID

Once confirmed working, add restrictions back incrementally — first HTTP referrer or IP, then API target restrictions — retesting after each change.

Step 7: Check Cloud Console Error Logs

# Stream live API errors from Cloud Logging
gcloud logging read \
  'protoPayload.serviceName="maps-backend.googleapis.com" severity>=ERROR' \
  --project=YOUR_PROJECT_ID \
  --limit=50 \
  --format='table(timestamp, protoPayload.status.code, protoPayload.status.message)'

This will surface server-side errors that your client code may be swallowing.