Agent skill
serpapi-common-errors
Diagnose and fix SerpApi errors: invalid keys, exhausted credits, blocked searches. Use when SerpApi returns errors, empty results, or unexpected status codes. Trigger: "serpapi error", "fix serpapi", "serpapi not working", "serpapi empty results".
Install this agent skill to your Project
npx add-skill https://github.com/jeremylongshore/claude-code-plugins-plus-skills/tree/main/plugins/saas-packs/serpapi-pack/skills/serpapi-common-errors
SKILL.md
SerpApi Common Errors
Overview
Quick reference for SerpApi errors. Check search_metadata.status first -- it will be Success or Error. Error details are in search_metadata.error or error at the top level.
Error Reference
Invalid API Key
{ "error": "Invalid API key. Your API key should be here: https://serpapi.com/manage-api-key" }
Fix: Verify key at serpapi.com/manage-api-key. Check env var is loaded.
Account Disabled / Searches Exhausted
{ "error": "Your searches for the month have run out. You can upgrade your plan at https://serpapi.com/pricing" }
Fix: Check usage: curl "https://serpapi.com/account.json?api_key=$SERPAPI_API_KEY". Upgrade plan or wait for monthly reset.
Missing Required Parameter
{ "error": "Missing parameter: q. Please provide a search query." }
Fix: Each engine has different query params. Google/Bing use q, YouTube uses search_query.
Google CAPTCHA / Blocked
{ "search_metadata": { "status": "Error" }, "error": "Google hasn't returned any results for this query." }
Fix: SerpApi handles CAPTCHAs automatically, but unusual queries or very high volume may trigger blocks. Try different location or wait.
Empty Organic Results (Not an Error)
result = client.search(engine="google", q="xyzzy123nonexistent")
if not result.get("organic_results"):
# Not an error -- query just has no results
# Check for answer_box, knowledge_graph, etc.
print("No organic results, checking other components...")
print(f"Answer box: {result.get('answer_box')}")
print(f"Related searches: {result.get('related_searches')}")
Quick Diagnostic
# 1. Check API key and account status
curl -s "https://serpapi.com/account.json?api_key=$SERPAPI_API_KEY" | jq '{
plan: .plan_name, used: .this_month_usage, remaining: .plan_searches_left
}'
# 2. Test basic search
curl -s "https://serpapi.com/search.json?q=test&engine=google&api_key=$SERPAPI_API_KEY" \
| jq '.search_metadata.status'
# 3. Check search archive (last 10 searches)
curl -s "https://serpapi.com/searches.json?api_key=$SERPAPI_API_KEY" \
| jq '.[0:3] | .[] | {id: .id, status: .status, query: .search_parameters.q}'
Error Handling
| Error | Retryable | Action |
|---|---|---|
| Invalid API key | No | Fix key |
| Searches exhausted | No | Upgrade plan |
| CAPTCHA/blocked | Sometimes | Change location, wait |
| Timeout | Yes | Retry with backoff |
| Missing parameter | No | Fix request params |
| 500 server error | Yes | Retry 2-3 times |
Resources
- SerpApi Status
- Account API
- Playground (test queries interactively)
Next Steps
For comprehensive debugging, see serpapi-debug-bundle.
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
dockerfile-generator
Dockerfile Generator - Auto-activating skill for DevOps Basics. Triggers on: dockerfile generator, dockerfile generator Part of the DevOps Basics skill category.
branch-naming-helper
Branch Naming Helper - Auto-activating skill for DevOps Basics. Triggers on: branch naming helper, branch naming helper Part of the DevOps Basics skill category.
readme-generator
Readme Generator - Auto-activating skill for DevOps Basics. Triggers on: readme generator, readme generator Part of the DevOps Basics skill category.
makefile-generator
Makefile Generator - Auto-activating skill for DevOps Basics. Triggers on: makefile generator, makefile generator Part of the DevOps Basics skill category.
gitignore-generator
Gitignore Generator - Auto-activating skill for DevOps Basics. Triggers on: gitignore generator, gitignore generator Part of the DevOps Basics skill category.
pre-commit-hook-setup
Pre Commit Hook Setup - Auto-activating skill for DevOps Basics. Triggers on: pre commit hook setup, pre commit hook setup Part of the DevOps Basics skill category.
Didn't find tool you were looking for?