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.