Google Search Light Errors

Light uses the shared ErrorResponse shape with code, message, correlation_id, retryable, and details.

Error object

Field	Type	Description
`code`	string	Error code
`message`	string	Human-readable message
`correlation_id`	string \| null	Keep for support
`retryable`	boolean	Whether a retry may succeed
`details`	object \| null	Extra context

An unreadable request body may return 422 with a detail list instead of code.

Common status codes

HTTP	Meaning
401	Unauthorized. Check `X-Api-Key`.
402	No active Google Search Light plan, or its searches are used up. Buy or top up a plan.
408	Timeout. Retry later if appropriate.
422	No page or validation. See `NO_RESULTS` vs `UPSTREAM_BLOCKED`. Not billed when no page.
429	Too many requests at once or per minute for your plan. Slow down or move to a larger plan.
500	Internal error. Retry with backoff; keep `correlation_id`.
502	Upstream unreachable. Retry with backoff.
503	Google Search Light is temporarily unavailable. Retry later.

422: NO_RESULTS vs UPSTREAM_BLOCKED

NO_RESULTS (`retryable: false`)

Google returned no results for the query. Asking again usually does not help.

{
  "code": "NO_RESULTS",
  "message": "search blocked (empty) after 1 attempts",
  "correlation_id": "6f1d2a9c-3b7e-4c5a-9e21-0d8f4b7a1c33",
  "retryable": false,
  "details": { "reason": "empty", "attempts": 1 }
}

UPSTREAM_BLOCKED (`retryable: true`)

Google would not serve the query (for example captcha). The same query often works on another exit.

{
  "code": "UPSTREAM_BLOCKED",
  "message": "search blocked (captcha) after 3 attempts",
  "correlation_id": "0b8e7f42-91c3-4d6a-b5e0-2a7c9d13f846",
  "retryable": true,
  "details": { "reason": "captcha", "attempts": 3 }
}

Retry guidance

Respect retryable
Keep correlation_id when contacting support

Billing reminders

Failed requests with no returned page are free
Multi-page requests charge only pages_returned
format: "both" does not create a second page charge