Error Codes and Responses in the Search API

When the Custom Search JSON API cannot fulfill a request, it returns an HTTP status code in the 4xx or 5xx range and a structured JSON error body. Parse the error.code and error.status fields to identify the problem programmatically and surface a meaningful message to your users or alerting system.

Error Response Structure

Every error — regardless of status code — follows the same envelope format. Familiarize yourself with this shape before reading the per-code reference below.

{
  "error": {
    "code": 403,
    "message": "Quota exceeded for quota metric 'customsearch.googleapis.com/requests'...",
    "status": "RESOURCE_EXHAUSTED",
    "errors": [
      {
        "message": "Quota exceeded for quota metric 'customsearch.googleapis.com/requests'...",
        "domain": "googleapis.com",
        "reason": "quotaExceeded"
      }
    ]
  }
}

Error Response Schema

object

required

Top-level error container. Always present when the HTTP status code is not 2xx.

Show error fields

integer

required

The HTTP status code as an integer (e.g., 400, 401, 403). Mirrors the response status line.

string

required

A human-readable description of the error. Do not parse this string programmatically — use error.status or error.errors[].reason for branching logic, as message text can change without notice.

string

required

A machine-readable gRPC status string. Use this field in switch/match statements. Common values: INVALID_ARGUMENT, UNAUTHENTICATED, PERMISSION_DENIED, NOT_FOUND, RESOURCE_EXHAUSTED, INTERNAL.

array

Optional array. Each element gives additional detail about one contributing error.

Show error.errors[] fields

string

A per-error message. Often identical to error.message but may be more specific when multiple problems occur.

string

The domain that generated the error, typically "googleapis.com" or "usageLimits".

string

A camelCase reason code for programmatic use (e.g., "quotaExceeded", "keyInvalid", "badRequest").

Quick Reference

HTTP Status	`error.status`	Typical Cause
`400`	`INVALID_ARGUMENT`	Missing required parameter, parameter out of range, or malformed value
`401`	`UNAUTHENTICATED`	API key is missing, deleted, or syntactically invalid
`403`	`PERMISSION_DENIED`	Key restriction violation, API not enabled, or wrong project
`403`	`RESOURCE_EXHAUSTED`	Daily quota (100 free queries/day) or per-minute rate limit exceeded
`404`	`NOT_FOUND`	Search Engine ID (`cx`) does not exist or was deleted
`429`	`RESOURCE_EXHAUSTED`	Per-second or per-minute request rate exceeded
`500`	`INTERNAL`	Transient Google-side error; safe to retry with backoff

Error Code Details

400 — Bad Request

400 Bad Request

A 400 means the request was structurally invalid before Google attempted to process it. The most common causes are a missing required parameter (key, cx, or q), a parameter value that falls outside the accepted range, or conflicting parameter combinations.error.status: INVALID_ARGUMENT

Example — Missing `q` parameter

{
  "error": {
    "code": 400,
    "message": "Request contains an invalid argument.",
    "status": "INVALID_ARGUMENT",
    "errors": [
      {
        "message": "Missing required parameter: q",
        "domain": "googleapis.com",
        "reason": "required"
      }
    ]
  }
}

Example — `start` value out of range

{
  "error": {
    "code": 400,
    "message": "Invalid Value",
    "status": "INVALID_ARGUMENT",
    "errors": [
      {
        "message": "Invalid Value",
        "domain": "youtube.parameter",
        "reason": "invalid"
      }
    ]
  }
}

How to resolve

Check that key, cx, and q are all present in the request.
Verify that num is between 1 and 10 and that start is between 1 and 91.
Ensure searchType, safe, imgSize, imgType, and other enum parameters use only documented values.
URL-encode the q value — unencoded special characters can truncate or corrupt the query string.

401 — Unauthorized

401 Unauthorized

A 401 means the API key provided is not recognized by Google. This occurs when the key has been deleted, was never created, or contains a typo.error.status: UNAUTHENTICATED

Example — Invalid API key

{
  "error": {
    "code": 401,
    "message": "API key not valid. Please pass a valid API key.",
    "status": "UNAUTHENTICATED",
    "errors": [
      {
        "message": "API key not valid. Please pass a valid API key.",
        "domain": "googleapis.com",
        "reason": "keyInvalid"
      }
    ]
  }
}

Example — No key supplied

{
  "error": {
    "code": 401,
    "message": "Request is missing required authentication credential. Expected OAuth 2 access token, login cookie or other valid authentication credential.",
    "status": "UNAUTHENTICATED"
  }
}

How to resolve

Confirm the key query parameter is present and spelled correctly (key, not apiKey or api_key).
Open Google Cloud Console → Credentials and verify the key exists and is not disabled.
If you recently deleted the key, create a new one and update all references.
Make sure you are not accidentally passing a different project’s key or a service account key (which is not valid here).

A 401 always means the key itself is unrecognized. If the key exists but lacks permission, the API returns 403 instead.

403 — Forbidden (permission / quota)

403 Forbidden

A 403 covers two distinct scenarios: permission problems (the key exists but is not allowed to make this call) and quota exhaustion (the key is valid but has hit a usage limit). Distinguish between them using error.status.

Scenario A — Permission denied

error.status: PERMISSION_DENIEDCommon causes: the Custom Search API is not enabled in the project, an API restriction blocks this API, or an application restriction blocks the caller’s IP/referrer/app.

{
  "error": {
    "code": 403,
    "message": "Custom Search API has not been used in project 123456789012 before or it is disabled. Enable it by visiting https://console.developers.google.com/apis/api/customsearch.googleapis.com/overview?project=123456789012 then retry. If you enabled this API recently, wait a few minutes for the action to propagate to our systems and retry.",
    "status": "PERMISSION_DENIED",
    "errors": [
      {
        "message": "Custom Search API has not been used in project 123456789012 before or it is disabled.",
        "domain": "googleapis.com",
        "reason": "accessNotConfigured"
      }
    ]
  }
}

How to resolve:

Enable the Custom Search API for your project at console.developers.google.com/apis/api/customsearch.googleapis.com.
If you have API restrictions on the key, ensure Custom Search API is in the allowlist.
If you have IP or referrer restrictions, confirm the request originates from an allowed source.
Wait up to 5 minutes after making changes for them to propagate.

Scenario B — Quota exhausted

error.status: RESOURCE_EXHAUSTEDThe project has consumed its daily or per-minute query budget.

{
  "error": {
    "code": 403,
    "message": "Quota exceeded for quota metric 'customsearch.googleapis.com/requests' and limit 'Queries per day' of service 'customsearch.googleapis.com' for consumer 'project:123456789012'.",
    "status": "RESOURCE_EXHAUSTED",
    "errors": [
      {
        "message": "Quota exceeded for quota metric 'customsearch.googleapis.com/requests'...",
        "domain": "googleapis.com",
        "reason": "quotaExceeded"
      }
    ]
  }
}

How to resolve:

The free tier provides 100 queries/day per project. If you need more, enable billing and purchase additional query capacity (up to 10,000 queries/day per project).
Check your current usage at Cloud Console → APIs & Services → Quotas.
Implement client-side caching to reduce duplicate queries.
Distribute load across multiple projects (each has its own free tier quota) if your use case permits.

Quota resets daily at midnight Pacific Time. Design your application to gracefully degrade — return cached results or a friendly “search unavailable” message — rather than surfacing a raw 403 to end users.

404 — Not Found

404 Not Found

A 404 typically means the Search Engine ID (cx) you supplied does not exist, has been deleted, or belongs to a different Google account.error.status: NOT_FOUND

Example

{
  "error": {
    "code": 404,
    "message": "Programmable Search Engine not found: cx=0123456789abcdef0:xxxxxxxxxx",
    "status": "NOT_FOUND",
    "errors": [
      {
        "message": "Programmable Search Engine not found: cx=0123456789abcdef0:xxxxxxxxxx",
        "domain": "googleapis.com",
        "reason": "notFound"
      }
    ]
  }
}

How to resolve

Log into programmablesearchengine.google.com and confirm the Search Engine ID shown in Setup → Basics → Search engine ID matches the cx value you are passing.
Search Engine IDs are case-sensitive. Copy-paste the value rather than typing it manually.
If you are using a cx created by another user, ensure they have shared it with your account.
If you deleted the search engine, create a new one and update your configuration.

429 — Too Many Requests

429 Too Many Requests

A 429 means you have exceeded the per-second or per-minute request rate limit, separate from the daily quota. This is a transient error — slow down and retry.error.status: RESOURCE_EXHAUSTED

Example

{
  "error": {
    "code": 429,
    "message": "Resource has been exhausted (e.g. check quota).",
    "status": "RESOURCE_EXHAUSTED",
    "errors": [
      {
        "message": "Resource has been exhausted (e.g. check quota).",
        "domain": "googleapis.com",
        "reason": "rateLimitExceeded"
      }
    ]
  }
}

How to resolve

Implement truncated exponential backoff:

After the first 429, wait 1 second and retry.
After each subsequent failure, double the wait time (1 s → 2 s → 4 s → 8 s …).
Add a small random jitter (e.g., ±500 ms) to prevent retry storms when many clients hit the limit simultaneously.
Cap the maximum wait at 32–64 seconds.
After 5–7 retries without success, surface an error to the user rather than retrying indefinitely.

import time
import random
import requests

def search_with_backoff(query, api_key, cx, max_retries=6):
    wait = 1
    for attempt in range(max_retries):
        resp = requests.get(
            "https://www.googleapis.com/customsearch/v1",
            params={"key": api_key, "cx": cx, "q": query},
        )
        if resp.status_code == 429:
            jitter = random.uniform(0, 0.5)
            time.sleep(wait + jitter)
            wait = min(wait * 2, 64)
            continue
        resp.raise_for_status()
        return resp.json()
    raise RuntimeError("Rate limit persisted after maximum retries.")

If you regularly hit 429 errors, consider batching queries, caching results for repeated searches, or distributing load over multiple projects.

500 — Internal Server Error

500 Internal Server Error

A 500 indicates a transient problem on Google’s infrastructure. The request was valid — the error is not caused by anything in your code. Retry with backoff.error.status: INTERNAL

Example

{
  "error": {
    "code": 500,
    "message": "Internal error encountered.",
    "status": "INTERNAL",
    "errors": [
      {
        "message": "Internal error encountered.",
        "domain": "googleapis.com",
        "reason": "internalError"
      }
    ]
  }
}

How to resolve

Retry the identical request after a short delay (start with 2 seconds).
Use the same exponential backoff strategy as for 429 errors.
If 500 errors persist for more than a few minutes, check the Google Cloud Status Dashboard for an active incident affecting the Custom Search API.
Log the full error body and the request parameters (excluding the API key) so you can file a support ticket if needed.

A 500 does not count against your daily quota. You will not be charged for requests that return 500.

Recommended Error Handling Pattern

Structure your error handling to branch on HTTP status code first, then on error.status for cases where a single status code covers multiple distinct problems (such as 403).

import time, random, requests
from requests.exceptions import HTTPError

def call_search_api(params: dict, max_retries: int = 6) -> dict:
    wait = 1
    for attempt in range(max_retries):
        resp = requests.get(
            "https://www.googleapis.com/customsearch/v1",
            params=params,
        )

        if resp.status_code == 200:
            return resp.json()

        try:
            body = resp.json()
        except ValueError:
            body = {}

        error   = body.get("error", {})
        code    = error.get("code", resp.status_code)
        status  = error.get("status", "")
        message = error.get("message", "Unknown error")

        if code == 400:
            raise ValueError(f"Bad request — fix your parameters: {message}")

        if code == 401:
            raise PermissionError(f"Invalid API key: {message}")

        if code == 403:
            if status == "RESOURCE_EXHAUSTED":
                raise RuntimeError(f"Quota exceeded: {message}")
            raise PermissionError(f"Access denied: {message}")

        if code == 404:
            raise LookupError(f"Search engine not found — check your cx: {message}")

        if code in (429, 500):
            # Transient — retry with backoff
            jitter = random.uniform(0, 0.5)
            time.sleep(wait + jitter)
            wait = min(wait * 2, 64)
            continue

        raise HTTPError(f"Unexpected error {code}: {message}")

    raise RuntimeError(f"Request failed after {max_retries} retries.")

async function callSearchApi(params, maxRetries = 6) {
  const base = "https://www.googleapis.com/customsearch/v1";
  let wait = 1000; // ms

  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const url = new URL(base);
    for (const [k, v] of Object.entries(params)) {
      url.searchParams.set(k, v);
    }

    const res = await fetch(url.toString());
    if (res.ok) return res.json();

    let body = {};
    try { body = await res.json(); } catch { /* ignore */ }

    const err     = body?.error ?? {};
    const code    = err.code    ?? res.status;
    const status  = err.status  ?? "";
    const message = err.message ?? "Unknown error";

    if (code === 400) throw new Error(`Bad request — fix your parameters: ${message}`);
    if (code === 401) throw new Error(`Invalid API key: ${message}`);
    if (code === 403) {
      if (status === "RESOURCE_EXHAUSTED") throw new Error(`Quota exceeded: ${message}`);
      throw new Error(`Access denied: ${message}`);
    }
    if (code === 404) throw new Error(`Search engine not found — check your cx: ${message}`);

    if (code === 429 || code === 500) {
      const jitter = Math.random() * 500;
      await new Promise(r => setTimeout(r, wait + jitter));
      wait = Math.min(wait * 2, 64_000);
      continue;
    }

    throw new Error(`Unexpected error ${code}: ${message}`);
  }

  throw new Error(`Request failed after ${maxRetries} retries.`);
}

API Overview

Base URL, required parameters, and response shape for the Custom Search JSON API.

Authentication

How to create, pass, restrict, and rotate API keys. Includes credential error examples.

​Error Response Structure

​Error Response Schema

​Quick Reference

​Error Code Details

​400 Bad Request

​Example — Missing q parameter

​Example — start value out of range

​How to resolve

​401 Unauthorized

​Example — Invalid API key

​Example — No key supplied

​How to resolve

​403 Forbidden

​Scenario A — Permission denied

​Scenario B — Quota exhausted

​404 Not Found

​Example

​How to resolve

​429 Too Many Requests

​Example

​How to resolve

​500 Internal Server Error

​Example

​How to resolve

​Recommended Error Handling Pattern

​Related Pages

API Overview

Authentication

Error Response Structure

Error Response Schema

Quick Reference

Error Code Details

400 Bad Request

Example — Missing `q` parameter

Example — `start` value out of range

How to resolve

401 Unauthorized

Example — Invalid API key

Example — No key supplied

How to resolve

403 Forbidden

Scenario A — Permission denied

Scenario B — Quota exhausted

404 Not Found

Example

How to resolve

429 Too Many Requests

Example

How to resolve

500 Internal Server Error

Example

How to resolve

Recommended Error Handling Pattern

Related Pages