Error Handling

Overview

rtrapy communicates with external services (Google Custom Search and Hugging Face Inference API) to retrieve and process information. The library is designed to handle API failures gracefully by logging the error to the console and returning a default empty value (e.g., an empty list or an empty string) instead of raising fatal exceptions.

Handling API Responses

When using the RTRAConnector, you should validate the output of your method calls to ensure the API requests were successful.

Google Custom Search Errors

The search() method queries the Google Custom Search JSON API. If the request fails (e.g., due to an invalid API key or exhausted quota), the method prints the status code and returns an empty list.

results = connector.search("query")

if not results:
    # This could indicate a 403 (Invalid Key) or 429 (Quota Exceeded)
    print("No results found or an API error occurred.")

Hugging Face Inference Errors

The generate_detailed_response() method interacts with the Hugging Face Inference API. If the model is currently loading, the API is down, or the authentication fails, the method returns an empty string.

response = connector.generate_detailed_response("query")

if response == "":
    print("Failed to generate a response from the AI model.")

Common Status Codes

While rtrapy abstracts the raw HTTP responses, you may see the following status codes printed in your console during troubleshooting:

| Status Code | Description | Troubleshooting | | :--- | :--- | :--- | | 400 | Bad Request | Ensure the query string is not empty or malformed. | | 401/403 | Unauthorized / Forbidden | Verify that your api_key and engine_id are correct and active. | | 429 | Too Many Requests | You have hit the rate limit for either the Google Search API or Hugging Face. | | 500/503 | Server Error | The external API service is temporarily down or, in the case of Hugging Face, the model is still loading. |

Troubleshooting Empty Data

If the methods return empty values without an explicit console error, check the following:

1. Google Search Index: Ensure your Programmable Search Engine ID (engine_id) is configured to search the entire web or that your specific sites contain the query keywords.
2. Snippet Availability: The combine_search_results helper depends on the snippet field from Google. if Google returns results without snippets, the text provided to the AI model will be empty.
3. Model Availability: The Hugging Face endpoint uses Mistral-7B-Instruct-v0.2. If this model is deprecated or moved, the API may return an unexpected data structure.

Best Practices for Error Management

Because the library returns default values on failure, it is recommended to implement "truthy" checks in your application logic:

from rtrapy.rtra_connector import RTRAConnector

connector = RTRAConnector(api_key="YOUR_KEY", engine_id="YOUR_ID")
query = "Python automation"

# 1. Check search results
results = connector.search(query)
if results:
    # 2. Check AI generation
    detailed_info = connector.generate_detailed_response(query)
    if detailed_info:
        print(detailed_info)
    else:
        print("Search succeeded, but AI generation failed.")
else:
    print("Search failed to return any items.")