HTTP & Error Handling

HTTP Requests and Response Handling

Eternity utilizes the requests library to communicate with the Google Custom Search JSON API. All data retrieval is performed via HTTP GET requests to the base endpoint: https://www.googleapis.com/customsearch/v1.

Response Behavior

When you invoke the search() method, Eternity evaluates the HTTP status code returned by the Google API:

Success (200 OK): The library parses the JSON response and returns a list of result items.
Failure (Non-200): If the API returns any status code other than 200, the library logs an error message to the console and returns an empty list ([]).

Error Handling in Practice

Since Eternity returns an empty list upon failure rather than raising an exception, you should implement checks to verify if data was successfully retrieved before processing results.

Example: Basic Error Checking

from eternity import Eternity

# Initialize the client
client = Eternity(api_key="YOUR_API_KEY", engine_id="YOUR_ENGINE_ID")

# Perform a search
results = client.search("Python documentation")

if not results:
    # This block executes if there was an HTTP error 
    # or if no results were found for the query.
    print("Search failed or returned no results.")
else:
    for item in results:
        print(f"Found: {item.get('title')}")

Common API Status Codes

Because Eternity is a wrapper for the Google Custom Search API, you may encounter specific status codes printed to your console. Understanding these codes helps in debugging configuration or quota issues.

| Status Code | Meaning | Troubleshooting | | :--- | :--- | :--- | | 200 | OK | Request was successful. | | 400 | Bad Request | Often caused by an invalid query or missing parameters. | | 403 | Forbidden | Your api_key or engine_id is invalid, or the API is not enabled for your project. | | 429 | Too Many Requests | You have exceeded your daily quota or the rate limit. | | 500/503 | Server Error | An issue occurred on Google's side. Retry the request later. |

Data Schema

When a request is successful, the search() method returns a list of dictionaries. Key fields typically include:

The get_combined_text() method internally handles these fields to provide a formatted string of the top 5 results. If the HTTP request fails, get_combined_text() will return an empty string.