14.6 Errors as design
- Approved by
- Panaversity ·
In everyday life. A good clerk who finds problems in a batch of 200 invoices does not stop at the first. She marks every problem with a note that says what is wrong and what to do, and hands the whole batch back. One trip, not twenty.
What you will learn. How to design what happens when the edge refuses: stop, collect every problem, and tell whoever owns the data what to fix.
Why it matters. On a run nobody watches, the report is what somebody reads.
How does a program stop itself?
By raising an exception: an error that stops the normal flow of a program. With one invoice in front of her, a clerk who finds a negative amount does not pay it and hope. She refuses it, with a note that says what is wrong. Code does the same in one line. Predict what prints, and what never does.
function checkAmount(cents: number): number {
// a negative amount breaks
// the rule: stop, with a note
if (cents < 0) {
throw new Error("amount must be zero or more");
}
// the rule held: hand it back
return cents;
}
console.log(checkAmount(482500));
console.log(checkAmount(-23450));
console.log("the next line");482500
Error: amount must be zero or more
at checkAmount (...)The first call passed, so its amount came back and was printed. The second broke the rule, so the function stopped at that line, and the program stopped with it. The last line never ran. The text in the error is the clerk's note. It is what somebody reads, so it says what is wrong.
How does code catch an error?
With try. Code that expects a failure puts the risky lines in a try block. If a line inside raises an error, the rest of that block is skipped, and the block that follows it runs instead. Then the program goes on. The function is the one above. Predict each line.
try {
checkAmount(-23450);
console.log("the next line");
// the note arrives here, in
// error. String(error) gives
// its kind, then its text
} catch (error) {
console.log("refused:", String(error));
}
console.log("the program goes on");refused: Error: amount must be zero or more
the program goes onCatching an error does not fix it. It is where the code decides what to do about it: here, to report it and carry on.
| TypeScript | Python | |
|---|---|---|
| Raise an exception | throw | raise |
| Catch one | try and catch | try and except |
When should a program stop?
When an input breaks a rule the program relies on, and before it calculates anything from that input. A refusal at the edge stops the run before any list or total exists.
Every program hands back one number as it ends. A program that finished hands back 0. The first program on this page stopped on its error, and handed back 1. A failure code is any number but 0, and it tells whatever started the run that it failed. Your agent reads it, and so does a job that runs on a schedule with nobody watching. The number is not in the program's own output. To see it, ask your agent what number the run ended with.
Stop at the first bad row, or collect them?
Collect them, so one report holds every problem. This is the good clerk: a note for every problem, and the whole batch handed back once.
Here it is with three rows and two rules. Predict how many problems it reports.
const rows = [
{ number: "INV-8301", amount: 482500, terms: "Net 30" },
{ number: "INV-8304", amount: -23450, terms: "Net 30" },
{ number: "INV-8306", amount: 158200, terms: "Net 10" },
];
// the clerk's pile of notes
const errors: string[] = [];
for (const row of rows) {
// a note, and keep going.
// push adds it to the end
// of the pile
if (row.amount < 0) {
errors.push(row.number + " amount must be zero or more");
}
// another note, and keep going.
// !== means "is not"
if (row.terms !== "Net 15" && row.terms !== "Net 30") {
errors.push(row.number + " terms must be one of the known terms");
}
}
// hand back the whole pile
for (const error of errors) {
console.log(error);
}
console.log(errors.length, "errors");Both print:
INV-8304 amount must be zero or more
INV-8306 terms must be one of the known terms
2 errorsNeither if stops the loop, so every row meets every rule. No exception is needed here: each problem becomes a note in the list, and the list is the report.
At work. Brightline's messy export, data/invoices-messy.csv, has 15 rows and four problems: a negative amount on line 5, terms "Net 10" on line 7, the date 2026-13-02 on line 11, and on line 14 a vendor id, V099, that is not in the vendor list. The agent's first loader stopped at line 5. The test Ana decided on expected four errors, with line numbers, and the second version passed it.
The second version is the small loop above, grown to full size. The two rules became the schema of 14.5, one more check asks whether each vendor id is in the vendor list, and each note carries its line in the file. On the messy file, the loader prints:
$ npm run check-invoices -- data/invoices-messy.csv
line 5 INV-8304 amountCents must be zero or more
line 7 INV-8306 terms must be one of the known terms
line 11 INV-8310 invoiceDate must be a real date, YYYY-MM-DD
line 14 INV-8313 vendorId V099 is not in vendors.csv
11 valid, 4 errors in data/invoices-messy.csvSo the 11 valid rows go no further. The loader checks every row, reports every problem, and only then stops with its failure code. Nothing is listed or totaled until the owner has fixed the file.
Who gets the report, and what does it say?
The person who owns the data. Each line names the row, the invoice, the field and what is allowed, so the owner fixes all four at once, with no questions.
Four choices come out of this lesson. Design each one from the start:
| Design choice | What it means | Brightline example |
|---|---|---|
| Fail loudly at the edge | Refuse bad input where it enters, with a clear message | The loader refuses a negative amount, until credits are decided |
| Never fail silently | Do not turn an error into a default value | The mistake to avoid: Brightline's invoiceFromRow turns a blank amount into $0.00 (14.5) |
| Collect, do not stop at the first | In a batch, check every record, then report them all | All four bad rows in one report |
| A message says what and what next | What failed, where, and what to try | "line 7, terms must be one of the known terms" |
When is a catch block wrong?
When it catches every error and carries on as if nothing happened, because that hides bugs. The function is the one from the top of this lesson. Predict what this prints.
let cents = 0;
try {
cents = checkAmount(-23450);
} catch {
// nothing here: the note
// is thrown away
}
console.log(cents);Both print:
0The amount was refused, the empty block threw the note away, and the program went on with $0.00 as if nothing had happened. When you see a block like this in agent-written code, ask: which error is this for, and what does the code do about it? If the answer is "nothing", it should not be there.
| Language | What a catch block catches |
|---|---|
| TypeScript | A TypeScript catch catches everything. With no name after it, as in catch {, it does not even keep the note. An empty catch {} is the shape to question first. |
| Python | A Python except names the kinds it catches, such as except ValidationError. A bare except: catches every error, and is the shape to question first. pass means "do nothing". |
What does refusing cost?
One bad row stops the whole run until its owner fixes it. That price is worth paying only when the rules are right: Marcus's run stopped for a credit that was never a mistake. Ana's rule assumes this export holds no credits, and if it ever does, the rule must change first. A run also need not stop whole: it can pay the valid rows and set the bad ones aside for their owner. Which is right depends on what a bad row would cost, so decide it in your brief.
Try it
The file in 14-6 checks three rows and collects every problem. Run it and investigate, as in 13.1.
Modify. Send: "Change the loop so it stops at the first problem. Don't run it yet." How many lines will it print now? Which problem disappears? Then ask the agent to run it.
Make. Decide what the person who owns the export needs to read. Then send: "Put the loop back so it collects every problem, and end each message with what to fix: [your words]. Don't run it yet." Read the messages, and then ask the agent to run it. Then ask: "What number did that run end with?" It reported two problems, so decide what that number should be. Then send: "Make the file end with a failure code when it finds any problem. Run it, and tell me the number it ends with."
What you should see. After your change in Modify, one problem and a count of 1. The bad terms on INV-8306 are never reported, so its owner would have to come back a second time. In Make, the run ends with 0 until you ask for a failure code, though it reports two problems. After you ask, it ends with a number that is not 0, usually 1.
The operating rule: refuse bad data loudly at the edge, before anything is calculated from it. Collect every problem in one report for whoever owns the data, each with its line and what to fix. Never let a catch block turn an error into a default value.

Figure 14.6. Collect, then report. One pass over the batch finds every problem, and one report goes back to the owner of the data.
Next. 14.7 gets the data from another program, which can change without telling you.
Check yourself
Question 1 / 7
0 answered
An agent wrote this helper to read amounts from a portal export.def cents(text: str) -> int:
try:
return int(text)
except ValueError:
return 0
for t in ["64000", "$640.00", ""]:
print(cents(t))What does it print?
Sources
- Owner
- Panaversity