Repository navigation
Conversation
There was a problem hiding this comment.
🟡 Changes recommended
The fully stubbed regression specs still fail without SERPAPI_KEY because the global setup hook raises before the examples run; the example group needs an api_key override.
1 open issue
What changed in this PR
Updates the Ruby client to return successful searches with empty results instead of raising, addressing the archive-retrieval problem in #17. Non-200 responses and searches marked Error still raise.
Changes:
- Changes JSON error handling and preserves error details when string keys are used.
- Adds stubbed regression specs for empty results and failure responses.
- Documents the breaking change and migration from exception handling to checking
results[:error].
| File | Description |
|---|---|
spec/serpapi/client/error_handling_spec.rb |
Adds coverage for empty results, string keys, and failed responses. |
README.md |
Explains error handling and migration for empty results. |
lib/serpapi/client.rb |
Revises failure detection and supports string-keyed error details. |
CHANGELOG.md |
Records the breaking behavior change and error-detail fix. |
Review effort: Balanced
| # and a top-level `error` message. Only non-200 responses and `search_metadata.status: Error` are failures. | ||
| # see: https://serpapi.com/api-status-and-error-codes | ||
| describe 'JSON error handling' do | ||
| let(:socket) { double } |
BREAKING CHANGE: JSON responses with HTTP 200 and a top-level error key no longer raise SerpApiError. SerpApi returns searches with empty results this way (search_metadata.status Success), so search, search_archive, and extract now return them as a Hash with the message in results[:error]. SerpApiError is raised only for non-200 responses or when search_metadata.status is Error. Code that rescued SerpApiError to detect empty results must check results[:error] instead. Also set SerpApiError#serpapi_error and #search_id when using symbolize_names: false. Fixes #17 Co-authored-by: Claude Opus 5.5 (xhigh effort) <noreply@anthropic.com>
77edff3 to
16f634f
Compare
adarshdigievo
left a comment
There was a problem hiding this comment.
AI disclosure: reviewed with GitHub Copilot using Claude Fable 5.2, Gemini 4 Carbon and GPT-6.2 Astra.
A few nits, nothing blocking.
Tested this live against v1.0.3, master and this branch (16f634f). The fix works: an empty-result search and its search_archive lookup raise on master and return here.
1. nit: extract now returns failed extractions without content (client.rb#L383)
extract goes through validate_json_content! too, and there the same shape is a failed extraction, not an empty result. client.extract(url: 'https://httpbin.org/status/404') returns HTTP 200, status: "Success", error: "Unsupported content: the URL did not return an HTML document." and no markdown. master raises on that; this branch returns the hash, so the README example and demo/demo_extract.rb print an empty line.
Returning seems fine since the changelog lists extract. Can we add a results[:error] check to those two examples, update the extract doc comment like search and search_archive, and add a spec for this response?
2. nit: the breaking-change note isn't true for symbolize_names: false (README.md#L197)
On 1.0.3 and master an empty-result search with string keys already returns the hash, because the old check only looked for :error. On this branch the message is at results["error"] and results[:error] is nil. Maybe say the change applies to the default symbol keys, and that string-key callers read results["error"].
3. nit: two spec regexes match messages the client doesn't produce (spec#L96, #L108)
Real responses carry an HTTP::Response::Status, so the message reads status: 503 Service Unavailable error: ... (that is what a live failed extract gives). The regexes only match because the double uses an Integer. Using HTTP::Response::Status.new(status) there and asserting response_status for the code would match what the client produces.
4. nit: Copilot's comment about SERPAPI_KEY is valid. I reproduced it locally: all 7 examples fail with the variable unset and pass with it set.

This addresses and fixes #17. I believe we need this change to be consistent here with the main API and how it works, as well as match how other integrations already works (like Python). Done with Opus 5.5 Extra high, notes below.
Breaking change
JSON responses with HTTP
200and a top-levelerrorkey no longer raiseSerpApi::SerpApiError. This affectssearch,search_archive, andextract.SerpApi treats a search where the search engine returned no results as successful: HTTP
200,search_metadata.status: "Success", and anerrormessage such as "Google hasn't returned any results for this query." (see Status and Error Codes). The client treated anyerrorkey as a failure, so these searches raisedHTTP request failed with status: 200 OK. Because the error drops the response body, there was also no way to read archived searches with empty results throughsearch_archive, which is what #17 reports.200,status: "Success",error(empty results)SerpApiErrorresults[:error]200,status: "Error"Search failed with status: Error error: ...)200(400, 401, 429, 503, ...)Migration
Code that rescued
SerpApiErrorto detect empty results must checkresults[:error]instead:SerpApiErroris still raised for failed requests and failed searches, so existingrescueblocks keep working for real errors.Since this is breaking, the next release should be a major version (2.0.0).
version.rbisn't bumped in this PR.Changes
lib/serpapi/client.rb: raise only for a non-200status orsearch_metadata.status == "Error". The status check also catches failed searches if the Search Archive API returns them with HTTP200.SerpApiError#serpapi_errorand#search_idare now also set withsymbolize_names: false. Before, they were alwaysnilthere.**BREAKING:**entry.Testing
spec/serpapi/client/error_handling_spec.rbwith stubbed HTTP responses. It covers empty results fromsearchandsearch_archive, string keys, failed searches returned with HTTP200, and non-200responses. 4 of its 7 examples fail againstmaster.bundle exec rake lintpasses.