When should a function raise an exception instead of returning an error value?

Ask what the caller is meant to do when this outcome occurs. If it is an ordinary possibility the caller should handle as part of the task, consider returning an explicit value. If the function cannot complete its promised operation, consider raising an exception so the caller can handle or propagate the failure separately.

For example, a search function might return None when there is no match, if absence is an expected result and cannot be confused with a valid match. By contrast, a function whose job is to load required content might raise if it cannot load that content.

In Python, raising an exception exits the current function and allows a handler farther up the call stack to catch it. [S2] That can help make a failure visible rather than treating it like an ordinary result. It does not mean exceptions are the right choice for every unsuccessful outcome.

A useful design question is: “Will callers commonly check for this outcome and choose what to do next?” If so, a return value may fit. Whatever you choose, document what the outcome means and what callers should do.

Suppose a program looks up a name in a mapping. “No matching name” is an expected outcome, so the function can return a value that the caller checks:

def find_user(users, name):
    return users.get(name)

user = find_user(users, "Mina")
if user is None:
    print("No match")
else:
    print(user)

Now suppose a function is meant to load a required file and return its contents. Returning an empty string on failure could make it unclear whether loading succeeded. Letting the failure raise gives the caller an opportunity to respond:

def load_config(path):
    with open(path, encoding="utf-8") as file:
        return file.read()

try:
    config_text = load_config(path)
except OSError as error:
    print(f"Could not load configuration: {error}")

These examples depend on their assumptions. If a configuration file is optional, its absence might instead be a normal outcome that the function represents explicitly. The important point is to avoid making a failure indistinguishable from a valid result. Catch an exception where you can respond meaningfully; otherwise, handling it farther up may be more appropriate.

Make the outcomes explicit in the function’s contract. If callers need to distinguish ordinary results, use clear named values or a documented result structure rather than ambiguous markers such as False, 0, or an empty string when those might also be valid results.

For example, a reservation check might have ordinary outcomes such as available and already_booked. A caller may need to respond differently to each, so a named status could be clearer than raising for one of them. If the check cannot be performed at all, decide whether the function should raise or return a separate failure result based on what callers need to do.

A C++/WinRT guideline recommends result or error codes for expected failures and exceptions for unexpected runtime errors. That is specific to C++/WinRT; it does not establish a Python rule. [S1] For your function, specify what each outcome means, whether it represents a usable result, and what action the caller should take.

Focus the review on the function’s contract and its callers. For each outcome, ask whether it is routine, what the caller should do, and whether the proposed representation could be mistaken for a valid result. Also check whether related functions use a compatible pattern, unless their contracts differ.

A review note can make the reasoning concrete:

Outcome: No matching record
Expected during normal use? Yes
Caller action: Show “not found” and continue
Choice: Return an explicit missing result

Outcome: Required file cannot be read
Expected during normal use? No, for this task
Caller action: Stop this operation and handle the failure
Choice: Raise an appropriate exception

These are example assumptions, not claims about your application. Replace them with the actual requirements and caller actions. Then document the choice so callers do not have to infer what a value or exception means.