serpapi-common-errors
/serpapi-common-errors
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".
- Author
- jeremylongshore ↗
- Repository
- tons-of-skills-marketplace ↗
- Licence
- MIT
- Last repository change
- 26.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 3
No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
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".
Triggers from the description
Arguments
/serpapi-common-errors [status-code|search-id] [engine]
Original author 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".
How it works
- Overview
- Prerequisites
- Tool Discipline
- Current Contract
- Authentication
- Instructions
- Output
- Error Handling
- Example
- Resources
SKILL.md preview
---
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
```python
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](https://serpapi.com/api-status-and-error-codes)
- [Account API](https://serpapi.com/account-api)
- [SerpAPI status](https://status.serpapi.com/)
## Next Steps
Keep the new fixture in the offline suite and review retry metrics after the next production window.
Versions
The database has no other skills named serpapi-common-errors.
Identical content appears in 1 other GitHub folders. We show one copy with the highest score.
Database snapshot: 13.11.2026 · package version f443004b2af0 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100serpapi-webhooks-events
Implement SerpAPI asynchronous searches and scheduled change detection without inventing a webhook callback contract. Use when building long-running searches or SERP monitoring. Trigger with "build SerpAPI async monitoring". - 100serpapi-install-auth
Install an official SerpAPI client, configure the private API key for server-side use, and verify account access without leaking credentials. Use when starting or repairing a SerpAPI integration. Trigger with "configure SerpAPI access". - 90search
Live, structured search results from Google, Google Maps, News, Shopping, Flights, Hotels, Scholar, Jobs, YouTube, Amazon, Walmart, and 100+ other engines through SerpApi. Use when the user asks to search with SerpApi, or needs current results such as local businesses and… - 100serpapi-tool
When the user wants to check live SERP results for a keyword, see what's in the local pack right now, check People Also Ask, see AI Overviews, verify SERP features, or do a quick spot-check of local search results. Trigger on "what shows up when you search," "check the SERP,"… - 100gamma-common-errors
Debug and resolve common Gamma API errors. Use when encountering authentication failures, rate limits, generation errors, or unexpected API responses. Trigger with phrases like "gamma error", "gamma not working", "gamma API error", "gamma debug", "gamma troubleshoot". - 100deepgram-common-errors
Diagnose and fix common Deepgram errors and issues. Use when troubleshooting Deepgram API errors, debugging transcription failures, or resolving integration issues. Trigger with phrases like "deepgram error", "deepgram not working", "fix deepgram", "deepgram troubleshoot", "transcription failed".