---

name: serpapi-common-errors description: 'Classify SerpAPI HTTP failures, search-status failures, and valid empty results before choosing a retry or repair. Use when searches fail, stall, or return unexpected shapes. Trigger with "diagnose a SerpAPI error".' argument-hint: "[status-code|search-id] [engine]" allowed-tools: Read, Glob, Grep, WebFetch, Write, Edit, Bash(python3:*) version: 1.6.0 author: Jeremy Longshore jeremy@intentsolutions.io license: MIT tags: [saas, serpapi, troubleshooting, errors, reliability] model: inherit effort: high compatibility: Designed for Claude Code; live reproduction and archive access require an authorized key and may affect allowance

SerpAPI Error Classification and Recovery

Overview

Diagnose the transport, account, search, engine, and application layers separately so retries do not hide configuration or quota failures.

Prerequisites

• HTTP status, safe error text, engine, normalized parameters, client version, and timestamp
• Search ID and search_metadata.status when a response was created
• Account owner approval before any live reproduction

Tool Discipline

Use Read, Glob, and Grep to trace request construction and parsing, WebFetch to verify current error semantics, Write or Edit for fixes and redacted evidence, and Bash(python3:*) only for an approved diagnostic using the official client.

Current Contract

SerpAPI uses conventional statuses: 400 for invalid requests, 401 for invalid authentication, 403 for forbidden accounts, 404 for missing resources, 410 for expired archive searches, 429 for either hourly throughput or exhausted searches, and 500/503 for server failures. Search status can be Queued, Processing, Success, or Error; Success can contain empty results.

Authentication

Keep SERPAPI_KEY out of exceptions and captured request URLs. Use the Account API to classify 429 responses, and share only redacted request metadata or search IDs with support.

Instructions

1. Capture the HTTP status, response error, search status, search ID, engine, safe parameter names, and client timeout.
2. Determine whether failure occurred before search creation, during queued/processing work, after a terminal error, or in local parsing.
3. For 400, compare parameters with the selected engine documentation and fix locally without retrying unchanged.
4. For 401/403, stop and repair account access; for 429, query Account API to separate throughput from allowance.
5. Retry timeouts and 500/503 only with a small attempt budget, exponential backoff, jitter, and idempotent processing.
6. Treat terminal Success with empty sections as data, then inspect documented engine-specific _state fields.
7. Add a sanitized regression fixture and record the classification, fix, retry count, and final state.

Output

Return the failure layer, status and search ID, retryability decision, evidence, corrective change, regression fixture, final state, and support escalation data.

Error Handling

Signal	Action
400	Correct parameters; no unchanged retry.
401/403	Stop; repair authorization or account state.
410	Re-run only with approval because the archive record expired.
429	Inspect account throughput and searches left before waiting or changing plan.
500/503 or timeout	Retry within budget; escalate persistent failures with search IDs.

Example

try:
    result = client.search(params)
except serpapi.HTTPError as exc:
    if exc.status_code in {400, 401, 403}:
        raise PermanentSearchError(exc.status_code) from exc
    if exc.status_code == 429:
        raise CapacityDecisionRequired() from exc
    raise TransientSearchError(exc.status_code) from exc

Resources

• Status and error codes
• Account API
• SerpAPI status

Next Steps

Keep the new fixture in the offline suite and review retry metrics after the next production window.