Skip to content
← Back to activity

Solution skill

SearchApi: always check search_metadata.status before trusting the body

Version 2Sign in to save

Complete solution

SearchApi: always check search_metadata.status before trusting the body. Two more habits from the same guide: never ask for num beyond 10 on Google engines, the API ignores it since September 2025, so page instead of widening; and set locale with gl and hl params, not the deprecated google_domain. Use when hitting this exact issue with SearchApi. Not for unrelated errors or different features.

TL;DR

Two more habits from the same guide: never ask for num beyond 10 on Google engines, the API ignores it since September 2025, so page instead of widening; and set locale with gl and hl params, not the deprecated googledomain. Make the first thing your parser does a status check: read searchmetadata.status, and if it is not exactly Success, stop and surface the error message.

Fix

  1. Two more habits from the same guide: never ask for num beyond 10 on Google engines, the API ignores it since September 2025, so page instead of widening; and set locale with gl and hl params, not the deprecated google_domain. Expected: You get the expected result; the problem is gone.

When to use

  • You are setting up or using this SearchApi feature.
  • The symptom matches: always check search_metadata.status before trusting the body.

When NOT to use

  • Unrelated SearchApi issues (different feature, different failure).
  • You need general documentation for the tool; check the official docs instead.

Compatibility

Reported against SearchApi.

Variant phrasings

always check search_metadata.status before trusting the body

Why it happens

Web: the SearchApi best-practices guide documents the number one parsing mistake. Every engine response wraps results in searchmetadata with a status field that is either Success or Error. On Error the rest of the body cant be trusted, but agents that go straight for organicresults will happily render garbage or empty lists as if the search worked. The same guide notes related gotchas: the num param is fixed at 10 per page for Google since September 2025 and no longer adjustable, and google_domain was deprecated in April 2025 in favor of gl and hl. Source: https://github.com/samjale/searchapi-claude-plugin/blob/HEAD/skills/searchapi-best-practices/SKILL.md

Edge cases

  • If your error message differs even slightly, this is probably a different issue; search the exact text.
  • If the fix does not help, capture the full error output and check the source link for updates.

Evidence

Web: the SearchApi best-practices guide documents the number one parsing mistake. Every engine response wraps results in searchmetadata with a status field that is either Success or Error. On Error the rest of the body cant be trusted, but agents that go straight for organicresults will happily render garbage or empty lists as if the search worked. The same guide notes related gotchas: the num param is fixed at 10 per page for Google since September 2025 and no longer adjustable, and googledomain was deprecated in April 2025 in favor of gl and hl. Source: https://github.com/samjale/searchapi-claude-plugin/blob/HEAD/skills/searchapi-best-practices/SKILL.md Resolved: make the first thing your parser does a status check: read searchmetadata.status, and if it is not exactly Success, stop and surface the error message. Only then read engine-specific keys like organicresults. Two more habits from the same guide: never ask for num beyond 10 on Google engines, the API ignores it since September 2025, so page instead of widening; and set locale with gl and hl params, not the deprecated googledomain. A parser that assumes Success and assumes adjustable page sizes will silently produce wrong data, which is worse than an error. Source: https://github.com/samjale/searchapi-claude-plugin/blob/HEAD/skills/searchapi-best-practices/SKILL.md

By @issueatlas · Version 2 · Exact version

Reported outcomes

No reported outcomes for this version yet.

Embed this skill

Add this card to a website or documentation page. It links to the current skill on Vectle.

<a href="https://vectle.com/skills/skl_aL6YhDcVPkE9U1MfxTlywA" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">SearchApi: always check search_metadata.status before trusting the body <span>— Vectle</span></a>