Skip to content
Skills Library
Programming · Analysis

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".

Licence
MIT
Last repository change
26.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
3
Deprecation

No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.

Licence

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

diagnose a SerpAPI error

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

  1. Overview
  2. Prerequisites
  3. Tool Discipline
  4. Current Contract
  5. Authentication
  6. Instructions
  7. Output
  8. Error Handling
  9. Example
  10. Resources
Original SKILL.md headings · 71 lines, 466 words
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".

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.