Handling Errors and Edge Cases Gracefully

A real network call can fail in many ways: no connection, a timeout, a malformed response. We build proper loading and error feedback instead of a program that silently hangs or crashes.

1. Learning Objective

2. Pre-Coding Quiz

Answer these before reading the concept explanation or writing any code. It is fine to get these wrong — that is the point. You need 4/5 to proceed to the lab.

3. The Concept — Robust Network Error Handling

Always set a timeout

Without a timeout, a request to an unresponsive server can hang the entire program indefinitely. A timeout guarantees the request either succeeds or fails within a bounded time.

import requests

try:
    response = requests.get(
        "https://www.apicountries.com/countries",
        timeout=5,  # give up after 5 seconds
    )
except requests.exceptions.Timeout:
    print("The request took too long and was cancelled.")

Catching distinct network failure modes specifically

The requests library provides specific exception types for different failure modes — catching them individually (Session 11's discipline) gives clearer, more actionable feedback than one generic catch.

import requests

def fetch_countries_safely():
    try:
        response = requests.get(
            "https://www.apicountries.com/countries",
            timeout=5,
        )
    except requests.exceptions.ConnectionError:
        return None, "Could not connect — check your internet connection."
    except requests.exceptions.Timeout:
        return None, "The request took too long and was cancelled."
    except requests.exceptions.RequestException as e:
        return None, f"An unexpected network error occurred: {e}"

    if response.status_code != 200:
        return None, f"The API returned an error (status {response.status_code})."

    return response.json(), None

A three-state model: loading, success, error

Rather than a silent pause followed by an unexplained result, explicitly represent and communicate what is currently happening — directly analogous to the loading/error states covered in the original React course this curriculum is modeled on.

def load_countries_with_feedback():
    print("Loading countries...")  # the "loading" state, communicated explicitly

    data, error = fetch_countries_safely()

    if error:
        print(f"Error: {error}")   # the "error" state, with a specific, useful message
        return []

    print(f"Loaded {len(data)} countries successfully.")  # the "success" state
    return data

Bringing it all together

This combines Session 11's exception discipline, Session 30's validation, Session 41's resource safety, and Session 42's API adaptation into one cohesive, defensively-built operation — the most robust piece of code in the entire project.

4. Lab

What you will build

A file called robust_loading_lab.py.

Step-by-step instructions

# robust_loading_lab.py
import requests

def fetch_countries_safely(url, timeout=5):
    try:
        response = requests.get(url, timeout=timeout)
    except requests.exceptions.ConnectionError:
        return None, "Could not connect — check your internet connection."
    except requests.exceptions.Timeout:
        return None, "The request took too long and was cancelled."
    except requests.exceptions.RequestException as e:
        return None, f"An unexpected network error occurred: {e}"

    if response.status_code != 200:
        return None, f"The API returned an error (status {response.status_code})."

    return response.json(), None

data, error = fetch_countries_safely("https://www.apicountries.com/countries")
if error:
    print("Error:", error)
else:
    print(f"Loaded {len(data)} countries")

data, error = fetch_countries_safely("https://this-domain-does-not-exist-12345.example")
print("Error:", error)
print("Data:", data)

data, error = fetch_countries_safely(
    "https://www.apicountries.com/countries",
    timeout=0.001,
)
print("Error:", error)

from country_explorer import CountryRepository, validate_country_record

def adapt_api_record(raw):
    return {
        "name": raw.get("name", "Unknown"),
        "region": raw.get("region", "Unknown"),
        "population": raw.get("population", 0),
    }

def load_country_repository(url):
    print("Loading countries...")
    raw_data, error = fetch_countries_safely(url)
    if error:
        print(f"Error: {error}")
        return CountryRepository(raw_data=[])

    adapted = [adapt_api_record(r) for r in raw_data]
    if adapted:
        validate_country_record(adapted[0])
    print(f"Loaded {len(adapted)} countries successfully.")
    return CountryRepository(raw_data=adapted)

repo = load_country_repository("https://www.apicountries.com/countries")
print(repo.get_all()[0].summary())

5. Expected Files Changed

6. Commit Checkpoint

Once the lab is complete and you can explain every line, make this exact commit:

git add robust_loading_lab.py docs/sessions/session-43/index.html
git commit -m "session-43: add timeouts, specific error handling, and loading/success/error feedback"

7. Code Review Checklist

Go through your code line by line and check each item:

8. Post-Coding Quiz

Same 5 questions. Take it again now that you have written and run the code. You need 4/5 to mark this session complete.

9. Reflection Questions

Think through these after the post-quiz. No right answer — they are for discussion.

10. What Breaks If This Knowledge Is Missing?

11. What We Learned